Installing and Configuring HyperServer

<< Click to Display Table of Contents >>

Navigation:  Developer's Guide > uniGUI HyperServer >

Installing and Configuring HyperServer

Installing and configuring HyperServer is quite easy and straightforward. uniGUI installer distributes HyperServer pre-compiled binaries under ..\uniGUI\HyperServer\bin\ folder (\bin64\ for 64-bit binaries).

This folder contains separate binaries for all available deployment methods: ISAPI DLL, Standalone Server and Windows Service:

 

..\uniGUI\HyperServer\bin\

..\uniGUI\HyperServer\bin\

 

 

These files are generic HyperServer server binaries and they can be configured to run any uniGUI application. In order to deploy HyperServer you need to copy HyperServer binary file to your uniGUI application folder. You are free rename HyperServer binary. In fact, you need to rename it if you want to run more than one instance of HyperServer on different ports. If you deploy in DLL mode then you may also rename the hyper_server.dll file to match your application name. HyperServer needs a configuration file which is required to provide various parameters for HyperServer. Configuration file has the extension of .CFG and should exits in same folder as HyperServer binary. If this file is missing one will be created automatically. You can also find default configuration files under same folder.

 

First step is to copy proper binary file based on your deployment method. For Standalone server use hyper_server.exe, for ISAPI DLL use hyper_server.dll and for Windows Service the correct file is hyper_service.exe.

Next step is to make proper changes to config file. Copy hyper_server.cfg file to your application folder and and open it using a text editor.

 

Express Configuration and Testing HyperServer

 

In order to quickly test HyperServer functionality you can go through an express configuration with configuring minimal parameters in the configuration file.

 

Copy hyper_server.exe and hyper_server.cfg to folder where your application's executable file resides.

Compile your application in Standalone Server mode. You may need to change your project's DPR file to switch from a different mode to Standalone Server.

Edit hyper_server.cfg file and set binary_name parameter to your application's executable name. For example binary_name=myapp.exe

Again hyper_server.cfg file set prompt_login=0

Run hyper_server.exe

In a browser tab navigate to url http://localhost:8077

You should be able to see your app's main form or login form in browser tab.

In order to access HyperServer control panel in another browser tab navigate to address http://localhost:8077/server

Choose HyperServer tab and you'll be able to observe HyperServer Nodes and various other information.   clip0145

Now at this stage you may test remote deployment option.

oGo back to your project and change a small visual detail.

oRe-compile your application.

oIn HyperServer control panel choose the Upload icon. clip0142

oSelect your newly compiled executable (myapp.exe) and press the Upload button.   clip0143

oComplete the upload and confirm the next dialog.

oYou will notice that all existing Nodes will be marked as Discarded. clip0144

oStart a new session in a new browser tab. Now you must be able to see new version of your application in the browser tab while older version of your application will still continue running in other tabs. You have successfully updated your app using remote deployment functionality of HyperServer.

 

 

Detailed Configuration

 

After you successfully could test your application using HyperServer now you need to make familiar yourself with various parameters in the HyperServer configuration file.

 

HyperServer Configuration Parameters

 

In configuration file you will see various parameters. Many of them can be left at their default values. Let's go through these parameters.

 

[transport]
pool_size=0

 

pool_size parameter is used to determine maximum size for transport handle pool.Total number of handles can not be bigger than this value. When is set to 0 HyperServer will try to calculate an optimum value.

Default value = 0

 

command_timeout=20000

 

HyperServer internally special commands to internally communicate with Nodes. command_timeout sets the amount of time HyperServer will wait until it get a respond from a Node after sending a command. Under normal conditions it must happen very fast (under a few millisecond). Default value is 20 seconds.

 

request_timeout=300000

 

The amount of time HyperServer will wait until a Node completes a request. When a web clients initiates an Ajax request, HyperServer will relay that request to related Node. HyperServer will wait until Node completes the request and sends a response back. Normally client will only wait for AjaxTimeout milliseconds, so request_timeout must be always bigger than maximum AjaxTimeout value used in the Nodes.

 

Default value is 300 seconds (5 minutes) which is much higher than a typical AjaxTimeout value which is 30 seconds by default. The only case where you may need to increase request_timeout  value is when your application sets extraordinary high values for AjaxTimeout parameter of ServerModule in Nodes. i.e. when your app needs to process tasks that may take more than 5 minutes.

 

It is possible to set this parameter to a value close to AjaxTimeout parameter of Nodes. It will help to release transport handles sooner when there are many timeout conditions. If you want to tweak this parameter then make sure you set it to a value bigger than AjaxTimeout parameter. Add at least 10 seconds to be on the safe side. ( AjaxTimeout + 10,000 )

 

connect_timeout=20000

 

The amount of time HyperServer will wait until it can establish a connection with a Node. Under normal conditions it must happen immediately.

Default value is 20 seconds.

 

[http_transport]
start_port=16384

 

start_port parameter is used for HTTP transport. A transport is a channel which HyperServer uses to internally communicate with its Nodes. Each Node requires to own a unique transport id which for HTTP transports is actually a TCP port number. HyperServer needs to know a start value for ports. It will assign port numbers to Nodes based on this start value. In Windows many different values can be assigned to start_port. By default ports in range (1024 - 49151) are defined as user ports in Windows operating system.

 

In order to find out dynamic port range used reserved for OS you can use below command:

 

C:\>netsh int ipv4 show dynamicport tcp

 

Protocol tcp Dynamic Port Range
---------------------------------
Start Port      : 49152 

 

In a Windows Server OS with default settings you will get a response like above, which indicates that Windows dynamic port range starts from 49152.  It is important to know the start port for Windows dynamic ports, so they won't conflict with HyperServer transport channel ports.

 

HyperServer uses port 16384 ($4000) by default as start_port. With this configuration First Node (Node #0) will be assigned port 16384, Node #1 will be assigned port 16385 and so on.

 

If you plan to run more than one instance of HyperServer on same OS then port numbers should be arranged in a way that they won't conflict with each other. You must ensure that all Nodes will be assigned unique port numbers. This can be easily done by leaving port gaps for each HyperServer instance. It can be calculated using below formula:

 

<start_port for new HyperServer instance> = <start_port of previous HyperServer instance> + ( <max_nodes of previous HyperServer instance> × 3 ) + 8 

 

Consider that you plan to install three HyperServer instances on same server. Instances are configured with max_nodes parameters of 8, 16 and 16 respectively.

 

For 1st instance start_port is configured as 16384 ( or any other desired value )

For 2nd instance start_port should be configured as 16384 + ( 8×3 + 8 ) = 16416

For 3rd instance start_port should be configured as 16416 + ( 16×3 + 8 ) = 16472

 

As you can see, we are leaving some additional gaps between port start numbers. The reason for this is that under certain conditions total number of Nodes can grow beyond max_nodes parameter.

Default value = 16384

 

[hyper_server]
binary_name=

 

binary_name is name of the Node executable file. It is your uniGUI application which you should compile in Standalone Server mode. This file should reside in same folder as HyperServer. You should not specify any path for this file. Only file name and extension should be specified. Entries should be in <name>.exe format. For example: acounting_app.exe

 

initial_nodes=2

 

initial_nodes is the number of Nodes which will be initially created when HyperServer starts. HyperServer will also use this value to maintain a minimum number of Nodes in standby mode. When number of Nodes fall below this value new Nodes will be automatically created to match the initial_nodes value.

Default value = 2

 

max_nodes=8

 

Maximum number of Active Nodes in system. All incoming sessions will be distributed among Active Nodes. In practice total number of Nodes can be higher than max_nodes because when Nodes are purged or discarded they will continue to stay in memory for a while until they're recycled. In a typical scenario total number of Nodes will not exceed ( max_nodes × 2 )

Default value = 8

 

max_sessions=0

 

This parameter is intended to put a max limit for total number of sessions created under a HyperServer instance. This is achieved by adjusting MaxSessions property of individual Nodes. MaxSession is simply calculated by dividing max_sessions by max_nodes. Apparently, this method will not guarantee that total number of sessions will not exceed max_sessions. It is only a simple method to put a top limit on total number sessions.

Default value for max_sessions is 0 which means HyperServer will not try to set a value for MaxSessions property of each Nodes. In this case each Node will accept up to MaxSessions sessions which is you have set in your uniGUI application.

 

sessions_per_nodes=0

 

(This parameter is not implemented yet)

 

prompt_login=1

 

When set to 1, server monitor will ask for a user Id and password. It is important to protect server monitor with user accounts. HyperServer server monitor also embeds a new control panel which allows several additional functions such as remote deployment and Node monitoring. You can create up to 10 different user accounts in CFG file. Please see [login-x] section below.

 

If  you set this parameter to 0 then no credentials will be asked while accessing the server monitor. It is reasonable to do so at development stage when you're debugging and testing your app, but in production mode prompt_login should certainly be set to 1.

 

Server Monitor Login Screen

Server Monitor Login Screen

 

 

HyperServer Control Panel in Server Monitor

HyperServer Control Panel in Server Monitor

 

persistent_node_zero=0

 

In Terminology section we introduced a new term named Persistent Node Zero.

If your application needs a persistent Node then you must set this parameter to 1.

 

port=8077

 

This parameter applies for HyperServer instances running in Standalone Server and Windows Service modes. You need to assign a different port for each instance running on same computer. For ISAPI Module this parameter has no effect.

 

url_path=
url_referer=
ext_root=[ext]\
uni_mobile_root=[unim]\
uni_root=[uni]\
uni_packages_root=[unipack]\

 

All above parameters are directly assigned to ServerModule component of HyperServer. If you need to customized one of the ServerModule's properties such as ExtRoot then simply use the equivalent ext_root from above list and assign a proper value.

 

Example:

ext_root=C:\uniserver\extjs\[ext]\   ( Please see section Adjusting Paths for more details.)

 

framework_files_root=

 

This parameter is same as FrameworkFilesRoot property of UniServerModule. If uniGUI runtime and custom themes are installed using Windows installers there is no need to change this parameter. For Linux where there is no runtime installer you should assign a correct path to this parameter.

For example if your runtime files are under folder '/etc/fmsoft/unigui/unigui_runtime' then your configuration should look like: framework_files_root=/etc/fmsoft/unigui/unigui_runtime

 

max_connections=500

 

Note: this parameter only applies to Standalone and Service mode HyperServer instances.

 

Maximum allowed number of concurrent connections. The default value is 500 which should be enough for many scenarios. You may need to increase this value only when there are large number of concurrent requests which requires more than 500 simultaneous connections. This parameter should always be equal of bigger than max_requests.

 

http_max_pool=500

 

Note: this parameter only applies to Standalone and Service mode HyperServer instances.

 

In a uniGUI application HTTP connections are internally pooled. This feature allows to re-use connections and related threads when there are continuous incoming requests from same clients. This will help to avoid establishing new connections for each incoming request. This will improve performance speed up HTTP communication. On the other hand, each pooled connection will occupy certain amount of system resources such as memory and threads.

By default up to 500 connections will be pooled in a HyperServer instance. If your particular scenario needs more connections to be pooled you can increase this value, but make sure you know what you are doing before modifying this parameter.

 
max_requests=500

 

This parameter sets maximum concurrent requests which can be processed by HyperServer. More requests above this value will be queued. Default value of 500 is big enough for many typical application with average request load. It is recommended to leave it at default value.

 

dont_create_backup=0

 

When set it prevents HyperServer from creating backup when a new Node binary is uploaded. Normally HyporServer creates backup files when a new version of Node is uploaded. You can disable this feature by setting this parameter to 1.

 

antiflood_per_ip=0

 

This feature works exactly like ServerModule's ServerLimits.AntiFloodPerIP property, except it works on HyperServer level. Which means floods are detected and avoided before they reach Nodes.

This property implements a simple flood prevention mechanism by preventing sessions from being created too fast. Unit for this property is milliseconds. A zero value means that no flood prevention is applied. Values bigger than zero enforces flood prevention. With a non-zero value HyperServer keeps track of each IP address and the time interval between creating new sessions. If time interval between two session creation is less than value of antiflood_per_ip an exception will be raised.

 

For example, if this value is set to 1000, each remote IP should wait at least 1 second (1000 ms) before it can create a new session. For a typical HyperServer scenario, a value between 250 - 1000 must be enough. A value of 250 indicates that no more than 4 sessions can be created per second from same IP address.

 

It must be noted that group of computers in a LAN may expose same external IP address, so when they connect to a remote uniGUI application server it may look like they all share same IP address. It must be taken into consideration when adjusting a value for this property.

 

Important: Enabling this feature may conflict with uniGUI stress test tool. Naturally, the stress test tool will try to create multiple session from same IP address as fast as it can, so during stress test sessions this feature must be disabled by setting it to 0.

 

Default value is 0. (No anti-flood protection)

 

session_one_per_ip=0

 

This feature works exactly like ServerModule's ServerLimits.SessionRestrict property with a value of srOnePerIP. This feature can be enabled by setting this parameter to 1.

 

Important: Enabling this feature may conflict with uniGUI stress test tool. Naturally, the stress test tool will try to create multiple session from same IP address as fast as it can, so during stress test sessions this feature must be disabled by setting it to 0.

 

Default value is 0. (Disabled)

 

detailed_log=0

 

Allows adding additional information to the HyperServer log file. There are cases where you need to observe how Nodes are created and destroyed. This additional information will allow you to closely follow this process.

 

server_title=

 

This parameter will allow you to change the default title of HyperServer which is shown in server control panel and the tray icon.

 

[node_recycling]

 
enabled=1

 

This parameter enables node recycling operations.

 

recycle_after_idle_seconds=0

 

This parameter defines the amount of idle time which is allowed for Node before it will be recycled by the HyperServer. A value of 0 means that this feature is disabled.

Any non-zero value will enable this feature. For example if you set this value to 600, it means that Nodes will be recycled after 10 minutes of inactivity. Here inactivity means the time frame which no Ajax request is received by any of the catşve sessions. An Ajax request received by this Node will reset the idle time. It is important to know that this parameter should always be higher than SessionTimeout parameter of your Nodes. Otherwise there is a chance that a Node will be recycled while it still has active sessions.

 

For instance if SessionTimeout property of Node is 600.000 milliseconds then the recycle_after_idle_seconds property of HyperServer should be at least 600 seconds or more. Another important point is that you should avoid using MainModule's OnSessionTimeout event to extend session lifetime. Doing so will confuse HyperServer and it may terminate active sessions after recycle_after_idle_seconds interval is passed.

 

recycle_when_empty=1

 

When enabled Node will recycled when it becomes empty. i.e. when last session is destroyed it will be marked as purged and freed after a while. This option is enabled by default.

 

recycle_after_secs=3600

 

Please leave above parameter at the default value.

 

recycle_after_sessions=0

 

Please leave above parameter at the default value.

 

allow_remote_config=1

 

This will enable the possibility to configure HyperServer parameters from server control panel.

Enabled by default.

 

clip0221

 

Pressing the gear icon will open below form which will allow you changing various HyperServer settings:

 

clip0222

 

Warning: Please note that changing above parameters to invalid or wrong values will lead to HyperServer malfunction and may cause serious problems. Please make sure you know what you are doing before changing any of the above parameters.

 

You can disable this feature by setting this parameter to 0 in the CFG file.

 

[login-0]
user_name=
password=
admin=0
 

You can create up to 10 different user accounts which can log into server monitor. This accounts will be effective only when prompt_login parameter defined above is set.

admin parameter determines the access level of account. if you set admin=0 then account will only have monitor access otherwise setting admin=1 will grant administrative rights to the account.

 

[login-1]
user_name=
password=
admin=0
 

Same as above.

 
[custom_mimes]
mime_0_ext=
mime_0_type=
mime_1_ext=
mime_1_type=
mime_2_ext=
mime_2_type=
mime_3_ext=
mime_3_type=
mime_4_ext=
mime_4_type=
 
Custom mimes allows to add custom file types to HyperServer scope. Under normal conditions for security reason only safe file types are allowed to be transferred from the server. You can define as much as mimes needed here.

New mimes can be simply added by adding a entry to CFG file. Consider you want to enable access to files with extension of "7z".

 

You need to add below entry:

 

mime_0_ext=7z
mime_0_type=application/x-7z-compressed