Running on the Web

EZWeb Server

PxPlus EZWeb Server is an easy-to-use Web server that is ideally suited for use with iNomads, PxPlus Dashboard, PxPlus Web Services and PxPlus IDE Main Launcher (Web). For many low volume installations and/or development situations where all that may be needed is a standard Web server, EZWeb Server can meet this need by providing the following functionality:

Configuring EZWeb Server

When EZWeb starts, it looks in the starting directory for a configuration file (optional) called ezweb.conf, which is used to define additional configuration options. If this file is not found, then the defaults will be used, along with any other options that may have been specified when launching EZWeb. See Running EZWeb Server.

Note:
Lines in this file that start with "!" or "#" will be considered comments. Pathnames with spaces in them must be within double quotes.

(Support for pathnames with spaces was added in PxPlus 2019.)

Below is a list of the valid configuration directives that can optionally be used (in alphabetical order):

Directive

Description

accesslog _pathname_

This directive is used to enable the access log. The access log records all requests processed by the server.

The location and name of the access log file is determined by _pathname_. If the file specified by _pathname_ does not exist, it will be created. The directory itself must exist.

Log entries will be in the standardized Common Log Format (CLF). Using this format means that the EZWeb server access logs can be readily analyzed by a variety of Web analysis programs that support the Common Log Format.

Example:

     127.0.0.1 - - [10/Feb/2023:16:43:04 -0500] "GET /webster.pxp HTTP/1.1" 200 3892

Format:

     requester_ip identity authorization_user date request_info http_statusresponse_size

Where:

requester_ip

IP address that made the request to the EZWeb server.

identity

Not used by EZWeb server; will always be "-" (dash).

Some other servers may return the RFC 1413 identity (visit https://en.wikipedia.org/wiki/Ident_Protocol) of the client.

authorization_user

Not used by EZWeb server; will always be "-" (dash).

Some other servers may return the UserID of the requester as determined by HTTP authentication.

date

Square bracket surrounded date, time, and time zone that the request was received, in strftime (visit https://en.wikipedia.org/wiki/Strftime) format.

request_info

Quoted request information made up of the HTTP method, request URL, and HTTP protocol, all separated with spaces.

http_status

HTTP status code returned to the client.

response_size

Size of the response returned to the client, measured in bytes.

(The accesslog directive was added in PxPlus 2023.)

alias inbound_name alternate_pathname

This directive is used to redirect any request to inbound_name (or its subordinate files/directories) to a specified alternate_pathname.

host hostname pathname

This directive is used to provide for multiple host directories based on the host name on any inbound request.

nobrowse

If this directive is specified, the server will disable all directory browsing.

(The nobrowse directive was added in PxPlus 2018.)

pfxpswd password

This directive is used to indicate the PFX certificate password if a PFX certificate is defined for the secure directive. This can be blank or not defined to define an empty password.

(The pfxpswd directive was added in PxPlus 2019.)

port portno

This directive is used to set the port number to be used by EZWeb.

Note:
This directive is ignored if the port is passed in ARG(1).

privkey pathname

This directive is used to indicate the PEM file, which contains the certificate private key. This is needed only if you have defined the secure directive and have separate PEM files for the certificate and private key.

(The privkey directive was added in PxPlus 2019.)

root pathname

This directive is used to change the default root directory for EZWeb. By default, EZWeb will run in the *plus/inomads directory.

secure pathname

This directive is used to indicate the server is to run using SSL/TLS and to provide the PEM or PFX file, which contains the server certificate information.

Renewed certificates are automatically reloaded. See Automatic Security Certificate Reload.

(PFX support was added in PxPlus 2019.)

shutdown password

This directive specifies a password that can be used to provide for remote shutdown of EZWeb. A remote shutdown will occur if the EZWeb server receives a request for "/ShutDown?password".

Running EZWeb Server

EZWeb Server is launched either from the PxPlus IDE Main Launcher (see Method 1) or from the Command line by running *ezweb/server (see Method 2). By default, the program will run against port 80 (the standard Web port for HTTP requests) and will support the iNomads interface based on the parameters found in the *plus/inomads/inomads.conf file.

Method 1 - From the PxPlus IDE Main Launcher:

To start EZWeb Server from the PxPlus IDE Main Launcher, expand the Web Deployment category and select Launch EZWeb Server.

The Launch EZWeb Server window is displayed. The Secure check box allows you to enable (or disable) secure TLS/SSL mode for the EZWeb Server.

(The ability to enable/disable secure TLS/SSL mode for the EZWeb server was added in PxPlus 2022.)

This window consists of the following:

Port Number

Enter the TCP/IP Port number to be used by the EZWeb Server.

To set a different port number as the default, enter the desired port number and click the Save button. The next time you invoke the Launch EZWeb Server window, it will default to this port number.

Secure (HTTPS)

Check box that is used to enable/disable secure TLS/SSL mode for the EZWeb Server.

If the Port Number is 80 (the default HTTP port) and the Secure check box is selected, the Port Number will change to 443 (the default HTTPS port).

If the Port Number is 443 and the Secure check box is unchecked, the Port Number will change to 80.

(The Secure check box was added in PxPlus 2022.)

SSL Certificate

Specify a pathname to a PEM or PFX file that contains the server certificate information, or click the Query button to select a file.

For information on the type of certificate PxPlus uses, see PxPlus SSL/TLS Support.

(The SSL Certificate input was added in PxPlus 2022.)

Certificate Key

Specify a PEM file that contains the certificate private key, or click the Query button to select a file. The Certificate Key is needed only if you have two separate PEM files, one for the certificate and the other for the private key.

(The Certificate Key input was added in PxPlus 2022.)

PFX Password

Specify the PFX certificate password if a PFX certificate is defined for the SSL certificate. This can be blank or not defined to define an empty password.

(The PFX Password input was added in PxPlus 2022.)

Launch EZWeb

The text on this button reflects the current port number (e.g. Launch EZWeb on port: 80).

When this button is clicked, a message lets you know that EZWeb has started on the specified port number. If the Secure option was set to On, the message also indicates that EZWeb is running in secure (HTTPS) mode.

Following that, an EZWeb Server button displays in the system tray to indicate that it is running in the background. Hover over this button to display a tooltip showing the port number. If the Secure option was set to On, the tooltip shows ";secure" after the port number (e.g. PxPlus-version_number:Ezweb Server (8088;secure)).

(Support to show EZWeb running in secure mode was added in PxPlus 2022.)

When a different port number is entered, the Launch EZWeb button immediately reflects the port number specified, indicating that EZWeb will launch on that port when this button is clicked.

Note:
If you launch multiple instances of EZWeb Server at a time, an EZWeb Server button displays in the system tray for each instance.

To keep track of the port number on which each instance is running, hover over each EZWeb button to display the tooltip showing the port number.

Save

Saves the port number, along with the secure settings (if specified). The next time you invoke the Launch EZWeb Server window, it will default to the saved port number and secure settings.

If you only want to run an instance of EZWeb Server on a particular port but not save that port number as the default, then do not click the Save button. Simply select the Launch EZWeb button to start EZWeb on the port you just specified.

Exit

Closes the Launch EZWeb Server window without launching EZWeb Server and does not save any changes.

(The ability to launch and save specific port numbers was added in PxPlus 2016.)
(The EZWeb tooltip was added to the system tray in PxPlus 2016.)

Method 2 - From the Command Line:

pxplus.exe -bkg *ezweb\server [-arg port [security[root]]]

Where:

port

This argument is used to set the port number to be used by EZWeb.

If the port argument is omitted, the port will default to the port defined in ezweb.conf, and if that is not defined, then port 80 will be used.

security

This argument is used to indicate that the server is to run using SSL/TLS and to provide the pathname to a PEM or PFX file, which contains the server certificate information.

If the pathname contains spaces or one of the options below is needed, this argument should be within double quotes. Options are supported and can be included by appending a space and one of the following to the security argument:

privkey=pathname

This option is used to indicate the PEM file, which contains the certificate private key. This is needed only if you have defined the security argument and have separate PEM files for the certificate and private key.

pfxpswd=password

This option is used to indicate the PFX certificate password if a PFX certificate is defined for the security argument. This can be blank or not defined to define an empty password.

The secure directive in the ezweb.conf file overrides this argument if defined. If neither this argument nor the secure directive in ezweb.conf is defined, EZWeb will run without SSL/TLS encryption.

Renewed certificates are automatically reloaded. See Automatic Security Certificate Reload.

(PFX support, the privkey option and the pfxpswd directive were added in PxPlus 2019.)

root

This argument is used to change the default root directory for EZWeb. The root directive in the ezweb.conf file overrides this argument if defined. If neither this argument nor the secure directive in ezweb.conf is defined, EZWeb will run in the *plus/inomads directory.

Examples

Example 1 - To run the EZWeb Server on port 8080, you could use the following Command lines:

 

Windows:

 

"C:\PVX Plus Technologies\PVX Plus\pxplus.exe" -bkg *ezweb\server -arg 8080

 

UNIX/Linux:

 

/pxplus/pxplus "*ezweb/server" -arg 8080

Example 2 - If you have a security certificate called mycert.pem that you would like to use, then your Command line would look something like this (note the use of port 443, which is the default port for secure HTTPS):

 

Windows:

 

"C:\PVX Plus Technologies\PVX Plus\pxplus.exe" -bkg *ezweb\server -arg 443 mycert.pem

 

UNIX/Linux:

 

/pxplus/pxplus "*ezweb/server" -arg 443 mycert.pem

Example 3 - If using an SSL certificate that is not in the single PEM file format, then your Command line would look something like this (note the use of port 443, which is the default port for secure HTTPS):

 

Windows:

 

"C:\PVX Plus Technologies\PVX Plus\pxplus.exe" -bkg *ezweb\server -arg 443 "C:\Users\User\SSL Certificate\mycert.pfx pfxpswd=mypassword"

 

UNIX/Linux:

 

/pxplus/pxplus "*ezweb/server" -arg 443 "/home/user/ssl certificates/mycert.pem privkey=/home/user/ssl certificates/mykey.pem"

Shutting Down EZWeb Server

To shut down EZWeb Server, use one of the following methods:

Method

Description

EZWeb Server button (System Tray)

Click the EZWeb Server button and then click on the tooltip "Shutdown EzWeb server (xxxx / y users)" (where xxxx = port number and y = user count).

If EZWeb Server is running in secure (HTTPS) mode, the tooltip shows ";secure" after the port number (e.g. Shutdown EzWeb server (8088;secure / 4 users)).

(EZWeb Server shutdown capability was added to the system tray in PxPlus 2016.)
(Support to show EZWeb running in secure mode was added in PxPlus 2022.)
(The user count in the tooltip was added in PxPlus 2023.)

Enter a remote termination request

To invoke a remote termination request, send the following URL:

     http://_servername_/ShutDown?uuuuuuu-ssssssss

Where:

 

uuuuuuu

User ID of the user who launched the EZWeb process

 

ssssssss

8-digit Serial Number of the PxPlus used to run EZWeb

The uuuuuuu-ssssssss code can be overridden in a *EZWeb config file with ShutDown=xxxxxx where xxxxxx is the value required (no limit) instead of User ID and Serial Number.

Installing as a Service on Windows

EZWeb Server can be installed as a Windows service using one of the following methods:

Method 1 - From the PxPlus IDE Main Launcher:

Expand the Installation and Setup category and select Install Windows Services to launch the Install Windows Services interface.

From the Type of Service drop box, select EZWeb Server. After entering the service settings in the grid, select the Install button.

Method 2 - Run the program *ezweb/install from the Command line:

It will ask you if you want to install the service.

If so, you will need to enter the Starting Directory (default is the *ezweb directory), the SSL Certificate and the Port Number to use:

     ->run "*ezweb/install"
     Service Not currently installed
     Do you want to install the service (Y/N):Y
     Starting directory............:C:\pxplus\lib\_ezweb
     SSL Certificate...............:
     Port to use...................:80

To delete or change the service settings, simply re-run *ezweb/install.

Once installed, you will need to run the Windows Control Panel and start the service manually. If desired, you can set the service to automatically start; however, the install script, by default, sets the service to Manual start.

Log Files

Error Log

You can create a directory in the EZWeb start directory called ezweb_logs (preferred by EZWeb) or create the directory called *ezweb/logs. The EZWeb Server will record each time it starts or stops, as well as any internal errors that it encounters, in textual log files within this new directory.

(Support for allowing an alternative directory was added in PxPlus 2023.)

The log files will be named:

YYYY-MM.log

Where:

YYYY is the current year.
MM is the current month.

These can be deleted at any time, if required.

Access Log

The accesslog _pathname_ directive is used to specify a location for the log file and enable the access log. The access log records all requests processed by the server.

(Support for using an access log was added in PxPlus 2023.)

Automatic Security Certificate Reload

All SSL/TLS security certificates have an expiry date and time. To avoid having users receive a security warning from the Web browser preventing access, it is important to renew SSL/TLS security certificates before they expire. After renewing the certificate, a manual restart of EZWeb is required to use it if using a version of PxPlus prior to PxPlus 2019.

As of PxPlus 2019, a restart of EZWeb is no longer required to use a renewed certificate. EZWeb will check for a renewed SSL/TLS security certificate as part of the first request after midnight. If a renewed certificate is found, EZWeb will automatically be updated to use the renewed certificate. Following that, any new connections will use the renewed certificate. Any existing connections will become unresponsive; however, refreshing the page will restore the session, and after that, it will use the renewed certificate.

It is important to keep this capability in mind if using a free Certificate Authority, such as Let's Encrypt, to get SSL/TLS certificates. Using Let's Encrypt, certificates expire in 90 days but can automatically be renewed.

For information on using Let's Encrypt with the PxPlus EZWeb Server, see Let's Encrypt SSL/TLS Certificates.

(EZWeb Automatic Security Certificate Reload was added in PxPlus 2019.)