Icon Configuring the Web Server

Elevate Web Builder includes a web server that can be used for serving up static content, including client browser applications. The web server is also an application server that provides a server application execution context as well as authentication, administration, database, and logging APIs and functionality. This web server is made available in several different versions.

Internal Web Server
For ease of use, the IDE includes an embedded version of the web server for development. By default, this web server is called Internal and is automatically set up during IDE startup with a specific configuration for use with the localhost loopback host and the standard HTTP/HTTPS ports 80 and 443. This configuration is stored in the ewbide.ini IDE settings file located here:

C:\Users\<UserName>\AppData\Local\Elevate Software\Elevate Web Builder 3\ewbide.ini

where <UserName> is the name of the user account under which the IDE is being run. The Internal web server configuration is stored under the Server_Internal section name in the ewbide.ini file.

Information This information is simply for reference, and you do not need to manually modify these settings in the ewbide.ini settings file. Instead, you can simply use the Server Manager to interactively modify the ports and other settings for the Internal web server. Please see the Using the Server Manager topic for more information on how to edit the settings for the Internal web server.

External Web Servers
In addition to the embedded version of the web server, two other external versions of the web server are provided with Elevate Web Builder:
  • A Windows service available as 32-bit and 64-bit executables for production


  • A Windows console application available as a 32-bit executable for development
The executables for these external web servers are installed in the following locations:

Image

These external web servers use an .ini file for storing their configuration in the following location:

C:\ProgramData\Elevate Software\Elevate Web Builder 3 Web Server

When any external web server is first started and the .ini configuration file does not exist in the above location, the configuration file will be created automatically with default values for all configuration entries.

The name of the .ini configuration file is determined by the name of the web server executable. For example, for the ewbsrvr.exe Windows service, the name of the .ini file would be ewbsrvr.ini.

Information If the web server finds an .ini with the proper name in the same directory as the server executable, it will use it instead of the .ini file in the common ProgramData directory for Windows.

By default, all of the configuration entries in the web server .ini configuration file are stored under a section called "Server". However, when running multiple web server instances, each section will have the following format:

[Server_<Server Name>]

where <Server Name> is the name of the web server instance. Please see the Multiple Server Instances topic for more information.

Server Name and Description
The web server can be given a name and description that are used for a few different purposes:
  • The server name is used to identify the service when running the web server as a Windows service.


  • The server description is used to describe the service when running the web server as a Windows service, and is used to identify the server via the Server header in the response to each HTTP request.
The configuration entries for the web server name and description are as follows:

Configuration EntryDescription
Server NameIdentifies the web server. The default value is "EWBSRVR".
Warning If using multiple web server instances, then each server instance would occupy a different section in the .ini file and need to have a different Server Name value. Failing to ensure a unique server name could result in Windows service name conflicts and other issues.
Server DescriptionSpecifies a more descriptive name for the web server. The default value is "Elevate Web Builder 3 Web Server".

Directory Structure
The default directory structure used by these external web servers looks like this:

Image

The configuration entries for the server directories are as follows:

Configuration EntryDescription
Content DirectorySpecifies the directory that the web server should use as the base directory for all static content, such as HTML files, JavaScript source files, image files, etc. The default value is "content".
Default DocumentSpecifies the default static HTML file to use if the root URL path is referenced without specifying a file name in a HEAD or GET HTTP request. The default value is blank ("").
Application DirectorySpecifies the directory that the web server should use as the base directory for the deployment of server applications. The default value is "applications".
Module DirectorySpecifies the directory that the web server should use as the base directory for the deployment of native server modules. The default value is "modules".
Log DirectorySpecifies the directory that the web server should use as the base directory for the storage of both the daily HTTP request logs (CSV) and the daily system logs (JSON). The default value is "logs".
Request LoggingSpecifies whether HTTP request logging is enabled (the default is 1).
LoggingSpecifies whether system logging is enabled (the default is 1).

Server Objects Database
Because the web server also acts like an application server, it requires a database for the storage of information about various server objects, including privileges, roles, users, databases, server applications, and native server modules. This database is called ewbsrvr.db and is, by default, stored here:

C:\ProgramData\Elevate Software\Elevate Web Builder 3 Web Server

The web server database uses a custom binary format that implements object versioning, allowing the various server objects to be updated in real time without requiring the web server to be restarted. This binary format is compressed when stored on disk.

The web server stores each user password in the database as the hash of a cryptographically-secure random value, called a "salt", plus the password.

All database writes are atomic: writes are first durably written to a transaction log file and then the database is updated. The web server will automatically recover from a database update failure during startup.

The configuration entries for the web server database are as follows:

Configuration EntryDescription
Database DirectorySpecifies where the ewbsrvr.db web server database is stored. The default value is "C:\ProgramData\Elevate Software\Elevate Web Builder 3 Web Server".
Max Database Write DelaySpecifies how long, in seconds, the web server waits after an update before writing the updates to the database. The default value is 2 seconds.
Password Salt LengthSpecifies the length of the password salt value. The default value is 16 characters.
Password Hash TypeSpecifies how the salt+password hash is generated, with 0 being an SHA-256 hash and 1 being an SHA-512 hash. The default value is 0.

Startup
By default, the web server will bind to all available IP addresses on all available local network interfaces, and will bind to two ports: the insecure HTTP port 80 and the secure HTTPS port 443.

Information Both ports must be available for the web server to be able to successfully start.

The web server can be configured so that all requests to the insecure HTTP port are automatically redirected to the secure HTTPS port.

The web server always uses long-lived connections and does not automatically drop the connection after a request. The default connection timeout is 30 seconds. Connections are serviced using a thread-per-connection model with threads provided on-demand from a thread cache with a default size of 128 threads. The default maximum of 2048 threads prevents excessive load from causing the web server to exceed the limits of the host operating system.

The configuration entries for the web server startup are as follows:

Configuration EntryDescription
IP AddressSpecifies the IP address that the web server should bind to. The default value is blank, or all local network interface addresses.
PortSpecifies the insecure HTTP port that the web server should bind to. The default value is 80.
Secure PortSpecifies the secure HTTPS port that the web server should bind to. The default value is 443.
Redirect to SecureSpecifies whether the web server should ensure that any requests to the HTTP port are redirected to the HTTPS port with a 301 HTTP status code (Moved permanently), with 1 being Yes and 0 being No. The default value is 0.
TimeoutSpecifies how long, in seconds, the web server will keep a connection open while waiting on a request. The default value is 30 seconds.
Max Request SizeSpecifies the maximum number of raw bytes that can be received in a request. The default is 67108864 bytes, or 64MB.
Warning The default file chunk size used by the IDE for file uploads is 16MB. Setting this value lower than 16MB will result in errors when uploading large files using the server manager in the IDE.
Authorized AddressesSpecifies a comma-delimited list of IP addresses that are permitted to connect to the web server. The IP addresses may include an asterisk as a wildcard character. The default value is "*", or all addresses.
Blocked AddressesSpecifies a comma-delimited list of IP addresses that are not permitted to connect to the web server. The IP addresses may include an asterisk as a wildcard character. The default value is blank (""), or no addresses.
Thread Cache SizeSpecifies how many threads can be cached for the purpose of servicing connections. The default value is 128 threads.
Max Num ThreadsSpecifies how many threads can be created for servicing connections before the web server refuses a connection. The default value is 2048 threads.

Request Routing
The web server only supports a small number of pre-defined routes for incoming HTTP requests.

Image

Incoming requests are routed according to the following rules:
  • Incoming HEAD or GET requests whose path/resource name matches an existing file present in the configured static content directory (see the Directory Structure section above) are automatically serviced without requiring any authentication or the creation of a new session.


  • If the request is not a HEAD or GET request for an existing static content file, then the request is routed based upon the path information in the request. If the initial portion of the path matches any of the pre-defined routes, then the request is routed and handled accordingly. If the request cannot be routed to any of the pre-defined routes, then a 404 Resource Not Found HTTP response code will be returned to the client performing the request.
Information If the route is to a separate API, then that API may use additional routing rules to direct the request to the proper request handling code, whether it is internal to the web server (as with the authentication, administration, or database APIs), or whether it is implemented in a server application or native server module.

The configuration entries for the web server request routing are as follows:

Configuration EntryDescription
Keep-Alive Resource NameSpecifies the resource name for keep-alive requests. The default value is "keepalive".
Authentication Resource NameSpecifies the resource name for authentication API requests. The default value is "authentication".
Administration Resource NameSpecifies the resource name for administration API requests. The default value is "administration".
Databases Resource NameSpecifies the resource name for database API requests. The default value is "databases".
Applications Resource NameSpecifies the resource name for server application requests. The default value is "applications".
Modules Resource NameSpecifies the resource name for native server module requests. The default value is "modules".
Debugger Resource NameSpecifies the resource name for debugger API requests. The default value is "debugger".

Session Handling
As mentioned above, any HEAD or GET requests to existing static content do not require authentication and, therefore, don't require a session. However, any other requests require authentication and the creation of a session before they can be successfully serviced by the web server.

A maximum number of authentication attempts can be specified for the web server so that any authentication attempts beyond that threshold will result in the user being locked out for a specified period of time.

Sessions are handled using an HTTP-only cookie with a cryptographically-secure random session ID with a default length of 32 characters. You can use the web server Redirect to Secure setting (see the Startup section above) to ensure that sessions are always established using secure connections. By default, sessions expire after 1800 seconds, or 30 minutes, but the session expiration time can be changed, and keep-alive requests can renew a session so that the session expiration time is reset.

Information Sessions are only created during an authentication request and are removed immediately if the authentication request fails.

The configuration entries for the web server session handling are as follows:

Configuration EntryDescription
Session ID LengthSpecifies the length of the random session ID. The default value is 32 characters.
Session ExpirationSpecifies, in seconds, how long a session will be kept in the web server without any activity. The default value is 1800 seconds, or 30 minutes.
Max Authentication AttemptsSpecifies how many authentication attempts can be made for a user before the user is locked out. The default value is 10 attempts.
Authentication Lockout TimeSpecifies how long, in seconds, a user is locked out after exceeding the maximum number of authentication attempts. The default value is 300 seconds, or 5 minutes.

Certificates
When run on Windows, the web server uses the cryptographic APIs available in the operating system for implementing secure TLS (Transport Level Security) web server connections, encryption, hashing, and random number generation. TLS is used to enable secure HTTPS connections to the web server (by default, listening on port 443). Certificates issued by a valid certificate authority are how client applications verify that they are indeed connecting to the intended host without being subjected to a man-in-the-middle attack. When an HTTPS connection is first made to the web server, a handshake occurs that provides the web server certificate along with any intermediate or root certificates that make up the chain of trust to the client. The client then verifies that these certificates are indeed valid, and disallows the connection if they are not.

On Windows, certificates are installed into a certificate store in one or more sets of certificate stores. There are separate sets of certificate stores for each user account, as well as one global set of certificate stores for the entire machine.

Certificates can be managed in several different ways:
  • Programmatically using Windows API calls


  • Programmatically using Windows PowerShell scripts


  • Interactively using the Microsoft Management Console with the Certificates snap-in
Certificates must meet some basic requirements in order to be considered valid:
  • The name of a certificate needs to match the host name that the client is trying to connect to (wildcard certificates are the one exception to this requirement). This means that the DNS entries that resolve to a specific IP address need to be correct and match the certificate name. For example, if the client is trying to connect to www.elevatesoft.com, then the DNS entries for www.elevatesoft.com should resolve to an IP address where a web server exists that will provide a valid certificate for the same www.elevatesoft.com domain.


  • If you are receiving a set of certificates from a certificate authority, then you will usually receive the host certificate along with an intermediate certificate (and, possibly, a root certificate). You will need to ensure that both the host certificate and the intermediate certificate are installed in a certificate store that is accessible to the web server. Common root certificates are typically already present in the certificate stores available in Windows through a program that allows Microsoft to distribute the common root certificates. However, if this is not the case, you can still install a root certificate into a specific certificate store as an administrator, if necessary.


  • Finally, installed certificates have an assigned expiration date and the host, intermediate, or root certificate cannot be expired. You can easily find out the expiration date of any installed certificate by interactively using the Microsoft Management Console or by programmatically interrogating the certificate information via PowerShell or the proper API calls.
Internal Web Server Certificate Installation

The IDE requires a localhost certificate to be installed for the current user in order to support secure HTTPS browser connections when running client browser applications in the IDE or from an external browser.

Warning This localhost certificate should only be used for development purposes because it is not signed by a valid certificate authority.

The internal web server embedded in the IDE will not start properly without this localhost certificate being installed, and you will see an error during the IDE startup if it is not present.

The ewbcert utility is included to automate the process of creating the proper localhost certificate for use with the IDE. You will find it in the following installation location:

C:\Program Files (x86)\Elevate Web Builder 3\bin\ewbcert\win32\ewbcert.exe

In order to allow the localhost certificate to work correctly with all modern browsers, the ewbcert utility first creates a root certificate called "EWBRootCA", and then uses that root certificate to create/sign the localhost certificate.

Command-line usage:

ewbcert <Certificate Name> [-s<Certificate Store Name>] [-t<Certificate Store Type>] [-c|-r]

Descriptions:
-s Certificate store name, enclose in double quotes (default is "My")
-t Certificate store type: CURRENT_USER or LOCAL_MACHINE (default is CURRENT_USER)
-c|-r Create/remove the certificate (default is to check for certificate)
Exit codes are 0 for success, 1 for failure

The following command can be used to create the localhost certificate for the IDE:

ewbcert localhost c

The following command can be used to remove the localhost certificate for the IDE:

ewbcert localhost -r

Information If you attempt to create a localhost certificate in a LOCAL_MACHINE certificate store, you will need to do so using a command prompt running with administrator privileges or the certificate creation will fail with an "Access denied" error.

The configuration entries for the web server certificate are as follows:

Configuration EntryDescription
Certificate NameSpecifies the name of the installed certificate that will be used for secure HTTPS connections. The default value is blank ("").
Certificate Store NameSpecifies the name of the certificate store where the certificate is installed. The default value is blank (""), which indicates the "My" certificate store (designated as the "Personal" store in Microsoft Management Console).
Certificate Store TypeSpecifies the type of the certificate store where the certificate is installed, with 0 being a CURRENT_USER certificate store and 1 being a LOCAL_MACHINE certificate store. The default value is 0.

Cross-Origin Resource Sharing
Cross-Origin Resource Sharing is a method used by browsers and other user agents to prevent HTTP requests to web servers whose origin differs from the origin of the current URL being accessed by the browser. The origin of a URL is:

Protocol//Domain [:Port]

Browsers accomplish this by sending a pre-flight OPTIONS request to the cross-origin web server, which then responds with either an HTTP 200 status code (OK) or an error status code. By default, the web server will respond to such requests with an HTTP 400 status code (bad request). Enabling the cross-origin resource sharing in the web server will cause the web server to respond with an HTTP 200 status code and subsequently allow the cross-origin request(s).

Warning The web server does not restrict cross-origin resource sharing by specific origins at this time. It simply allows or disallows all cross-origin requests.

The configuration entries for the cross-origin resource sharing are as follows:

Configuration EntryDescription
Enable Cross Origin ResourcesSpecifies that the web server will allow and handle cross-origin requests, with 1 being allow and 0 being don't allow. The default value is 0, or No.

Example Web Server Configuration File
For reference, the following is an example of a typical web server configuration file used for development with the 32-bit console version of the web server:

[Server]
Server Name=EWBSRVR
Server Description=Elevate Web Builder 3 Web Server
Database Directory=C:\ProgramData\Elevate Software\Elevate Web Builder 3 Web Server
Max Database Write Delay=5
Domain=
Default Document=
Content Directory=C:\ProgramData\Elevate Software\Elevate Web Builder 3 Web Server\content
Application Directory=C:\ProgramData\Elevate Software\Elevate Web Builder 3 Web Server\applications
Module Directory=C:\ProgramData\Elevate Software\Elevate Web Builder 3 Web Server\modules
Log Directory=C:\ProgramData\Elevate Software\Elevate Web Builder 3 Web Server\logs
Logging=1
Request Logging=1
Enable Cross Origin Resources=0
Keep-Alive Resource Name=keepalive
Authentication Resource Name=authentication
Administration Resource Name=administration
Databases Resource Name=databases
Modules Resource Name=modules
Applications Resource Name=applications
Debugger Resource Name=debugger
IP Address=
Port=81
Secure Port=444
Redirect to Secure=0
Timeout=30
Max Request Size=67108864
Authorized Addresses=*
Blocked Addresses=
Thread Cache Size=128
Max Num Threads=2048
Max Authentication Attempts=10
Authentication Lockout Time=300
Session ID Length=32
Session Expiration=1800
Password Salt Length=16
Password Hash Type=0
Certificate Name=localhost
Certificate Store Name=
Certificate Store Type=0
Image