Seanox Devwex 1.2013.0707
Copyright (C) 2013 Seanox Software Solutions
All rights reserved.

Seanox Software Solutions

Devwex - Advanced Server Developing

Documentation

Documentation of Seanox Devwex
Stand 1.2013.0707

Copyright © 2013 Seanox Software Solutions

All rights reserved.

Wichtiger Hinweis

Die im Buch genannten Software- und Hardwarebezeichnungen sowie die Markennamen der jeweiligen Firmen unterliegen im Allgemeinen warenzeichen-, marken- oder patent-rechtlichem Schutz.

Table of Content

General
Licence Agreement
Features
System Requirements

Installation

Configuration File
General Options
Initialize

Server
Virtual Hosts
Remote Control
Server Configuration
Secure Socket Layer / Transport Layer Security
Virtual Directories
System References
Basic- / Digest- Access Authentication
Common Gateway Interfaces
Environment Variables
Filters
Modules

Statuscodes
Mimetypes








[COMMON]
[INITIALIZE]

[SERVER]

[SERVER:REMOTE:BAS]
[SERVER:X:BAS]
[SERVER:X:SSL]
[SERVER:X:REF]
[SERVER:X:REF]
[SERVER:X:ACC]
[SERVER:X:CGI]
[SERVER:X:ENV]
[SERVER:X:FLT]


[STATUSCODES]
[MIMETYPES]












[VIRTUAL]

[VIRTUAL:X:BAS]

[VIRTUAL:X:REF]
[VIRTUAL:X:REF]
[VIRTUAL:X:ACC]
[VIRTUAL:X:CGI]
[VIRTUAL:X:ENV]
[VIRTUAL:X:FLT]


Note - The following documentation refers mainly to the HTTP instance of the server. The sections Licence Agreement, System Requirements, Installation, Configuration File, General Options and Initialize are general. Details for the modular architecture, start sequence and APIs are contained in the documentation to available Devwex SDK.

General

Devwex is a minimalistic web server with a modular architecture. The already contained servers instances support the HTTP amongst others virtual hosts, IP/Port sharing, directory index, filtering, modules, SSL/TLS, DCGI/CGI1.1 and a on telnet based remote access to control the server. Further servers and modules can be integrated about the available APIs. The server is a pure Java implementation for the command line and can be used with an appropriate Java runtime environment on many operating systems.

Licence Agreement

Seanox Software Solutions ist ein Open-Source-Projekt, im Folgenden Seanox Software Solutions oder kurz Seanox genannt.

Diese Software unterliegt der Version 2 der GNU General Public License.

Copyright (C) 2013 Seanox Software Solutions

This program is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Features

Architecture

Devwex is a multithreaded container for (server-)modules that are integrated through the available server and module API. Already contain a Telnet-based remote access and a HTTP(S) server, which is specially for web applications advanced module API. The custom classloader supports loading and unloading of servers and modules at the runtime.

Customizing

Error pages and the listing of directories (Directory Index), including the icons, which are used for visual support, the different data types assigned, based on templates can be customized for all physical and virtual hosts.

Expandability

The modular architecture and many interfaces allow you to change, extend and add functionalities.

Configuration

This is based on a central file. All servers, modules and other global settings are configured there in an enlarged INI format, which supports dynamic values and inheritance.

Monitoring

Functions such as status, restart and stop can be accessed via the configurable Telnet remote access. Alternatively Devwex itself provides an appropriate client.

Interfaces

(Fast)CGI - For data exchange and to connect external runtime environments and applications, the specification 1.1 of the Common Gateway Interface PHP, Perl, Python and others are supported. Optional FastCGI is also available.

DCGI - A specially designed interface for Devwex, like CGI 1.1, for various programming languages such as Java, VB, VB(A) and others, allows the connection of multithreaded environments or applications, which have no independent runtime environment.

Server and Module-API - On these can be connected servers and modules, modify existing or adding new features. The module container manages and controls all moduls, allowed changes at runtime and dispatches information on events.

HTTP(S) - Based on specification 1.0, is supported HEAD, GET, POST and also OPTIONS, PUT and DELETE of HTTP 1.1. Further methods can be provided by additional modules and by DCGI or CGI.

Telnet - For control and monitoring is a Telnet-based server-client solution, including an API for Java, available.

WebSocket - A network protocol based on TCP, that supports a bidirectional communication between web applications and web server.

Security

For the secure transmission of data, Secure Socket Layer (SSL) and Transport Layer Security (TLS), with server and client certificates, is supported. Certificates can be assigned individually for each physical host, by inheritance in groups or globally.

Access to directories and files can be provided with Basic- and Digest-Access-Authentication, which support the administration of groups. In addition, access can be controlled by filters, that freely definable rules, that support individual error pages, automatic redirects and modules.

Virtualization

IP, port and name-based (Virtual Domain) Hosting will supported.

System Requirements

Software

Java Runtime 1.4.x oder höher

Hardware (Minimum)

Processor 200 MHz
Memory 64 MB
Network 10 MB/s

Installation

After unpacking the installation directory can be put anywhere in the file system.

For SSL and TLS, the Java Secure Socket Extension (JSSE) is used. Since Java version 1.4.0 this extension is a part of Java Runtime Environment (JRE) or Java Development Environment (JDK).

After the console (shell/prompt) has opened, must be changed the work directory into ./devwex/program. Here the Server can be started directly as java binary or with the available start scripts.

Java Binary

java -cp devwex.jar [-Dlibraries=value] [-Dparameter=value] com.seanox.devwex.Service [option]

Start script for Windows (command prompt)

devwex.bat [option]

Start script for Unix/Linux (Shell)

devwex.sh [option]
Option
Description
start
starts with the given configuration
state
shows the starting and current time and all running servers
restart
ends all active servers and restarts with the given configuration
stop
terminates Devwex with all running servers
*
enable verbose output (i.e. start*)

Tip - Devwex extends the classpath automatically when starting by all files of the directories, which by the starting parameter -Dlibraries was indicated.
Tip - With Devcox is a web based administration for Devwex available. With this the configuration and administration is done directly through the web browser.
Tip - Remote access for server control is via telnet. Most operating systems already contain the appropriate client can use the console (shell/command prompt) as follows.

i.e. telnet 127.0.0.1 25000   
                              
     STATE                    
     VERS: 1.2013.0707       
                              
     TIME: 2013-07-07 06:00:00
     TIUP: 2013-07-07 06:00:00
                              
     SERV: TCP 127.0.0.1:25000
     SERV: TCP 127.0.0.1:80   
     SERV: TCP 127.0.0.1:443  
Tip - The entry of IP addresses in the host file on the operating system as Windows (i.e c:\windows\system32\drivers\etc\hosts) or Unix (i.e. /etc/hosts), to determine the host name and can thus access to network resources, such as Servers and databases, be accelerated.

Configuration File

The configuration file devwex.ini is organized in six sections and will be used from the current work directory where the server was started. After installation contains the directory ./devwex/program already preconfigured devwex.ini.
Section
Description
[COMMON]
general application options
[INITIALIZE]
module initialization with (re)starting the service
[SERVER]
configuration area for physical servers
[VIRTUAL]
configuration area for virtual hosts of HHTP servers
[STATUSCODES]
status codes of HTTP servers
[MIMETYPES]
assignment of media and data types

Devwex used for configuration an extended INI format. Data is also stored line by line as section with key, also called as a parameter, and value. Names of the sections and keys are not case sensitive. Multiple or repeated declarations will be put together: already existing entries will be overwritten and new entries added. For that reason it is possible to separate sections in the configuration file, although this proceeding could complicate clarity.

As an extension to the original format can be inherited sections. After the section the keyword EXTEND bowl, and the names of referencing section is specified. The derived section then takes over all the keys and values in the referenced section, and can extend or override this.

Assigning a value is a key on the equal sign. In derogation from the original format, the allocation of value can proceed to the next line if it begins with a plus sign. A value assignment can be fixed or variable. With the option [?] at the end of a key, the referred value will first be determined using the system properties of the Java environment. If this can not be found, the optionally given value will be used. Without a value is a key with the option [?] not specified, and so is ignored.

The semicolon is interpreted as commentary sign. The following characters will not become part of value assignments or declarations. In derogation from the original format, a comment may be used at any position in a line. The option [+] at the end of a parameter or value assignment will skip any given commentary sign in the line. So the semicolon can be used for assigning values.

i.e. 1: [SECTION] EXTENDS SECTION-A              ;comment
     2:   PARAM-A         = VALUE-1              ;comment
     3:   PARAM-B         = VALUE-2; VALUE-3 [+]         
     4:                   + VALUE-4; VALUE-5 [+]         
     5:   PARAM-C     [+] = VALUE-6; VALUE-7             
     6:   PARAM-D  [?][+] = VALUE-8; VALUE-9             
     7:   PARAM-E  [?]    = VALUE-0              ;comment
     8:   PARAM-F  [?]                           ;comment
Line
Description
1
The section named "SECTION" is defined. With the option EXTENDS is inherited from the section "SECTION-A". Therefore be with the section "SECTION" all over EXTENDS involved directly and/or indirectly given sections. The characters after the semicolon are interpreted as comment.
2
The value "VALUE-1" is assigned to the key "PARAM-A". The characters after the semicolon are interpreted as comment.
3
The values "VALUE-2; VALUE-3" are assigned to the key "PARAM-B". The option [+] skips the commentary function of the semicolon. All values are used. It is not possible to put are comment in this line.
4
The value allocation of line 003 will continue and the value of "VALUE-4; VALUE-5" to the value of key "PARAM-C". The option [+] skips the commentary function of the semicolon. All values are used. It is not possible to put are comment in this line.
5
Similar to line 003 the values "VALUE-2; VALUE-3" are assigned to the key "PARAM-C". The option [+] skips the commentary function of the semicolon. All values are used. It is not possible to put are comment in this line.
6
The value assignment for the key "PARAM-D" is handled dynamically. The value will first be determined using the system properties of the Java environment. Therefore, the key part of the current runtime environment or must be passed when starting the program in the form -Dparameter=value. Upper and lower case will not be applied. The key which are defined in this way are recognized with the complete value assignment. Comments are not supported with this option. If a value for the parameter can not be determined using the system properties then the given values "VALUE-8; VALUE-9" are used. Comments can not be used with the option [+].
7
Similar to line 006 the key "PARAM-E" will be determined using the system properties of Java. If this fails, the optionally given value will be used. Without the option [+] a comment can be used.
8
Similar to the lines 006 and 007 the key "PARAM-F" will be determined using the system properties of Java. If this is not possible, the parameters are not accepted.

General Options

[COMMON]

General and globally available options for servers, hosts and modules are defined here.
Parameter
Value
Description
CLEANUP
5000
interval in milliseconds for smart clean up of resources, the java garbage collector was used only by deallocate resources
RELOAD
ON|OFF
option for automatic reload and restarting from the server on changes of the configuration file

Initialize

[INITIALIZE]

With (re)starting the service will initialize the defined modules and informed about certain events. Arguments also can optionally be submitted.

Syntax for building modul definition

NAME = RESOURCE [OPTION] [OPTION] ...

Example for a definition of modul

CONTAINER = com.seanox.module.Container [SIZE:256] [TYPE:FIFO]

A modul can be marked as optional with [*]. If the extension not contained at initialization of modules, it does not come to a error output.

Example for a optional definition of modul

CONTAINER = com.seanox.module.Container [SIZE:256] [TYPE:FIFO] [*]

Server

Server as physical hosts offer network access to a specific IP address and a specific port. When starting Devwex all servers are identified in the configuration file using the pattern [SERVER:*:BAS] in the name of the section and started.

Syntax for building server

[SERVER:NAME:SECTION]

The name of server can be chosen freely and set.

The server configuration consists of seven sections.
Section
Description
[SERVER:X:BAS]
basis configuration
[SERVER:X:REF]
virtual directories
[SERVER:X:ACC]
access control list
[SERVER:X:ENV]
environment variables
[SERVER:X:CGI]
CGI assignment und configuration
[SERVER:X:FLT]
filter configuration

Virtual Hosts

Virtual hosts are available to all servers for a name-based (Virtual Domain) hosting available. What makes an IP and port for sharing. A virtual host uses the configuration of the calling server. With the configuration to a virtual host will be overwritten targeted. The use of virtual hosts based on the incoming request to the server. According to the enclosed host is then used the same name virtual host.

Example of an request to a virtual host

GET /directory/file.cgi?value=123 HTTP/1.1
Accept-Encoding: gzip, deflate            
Accept-Language: de                       
Accept: */*                               
User-Agent: Browser                       
Host: www.xxx.zzz                         

Following this example must be created in configuration file for the virtual host the following sections.
Section
Description
[VIRTUAL:WWW.XXX.ZZZ:BAS]
basis configuration
[VIRTUAL:WWW.XXX.ZZZ:REF]
virtual directories
[VIRTUAL:WWW.XXX.ZZZ:ACC]
access control list
[VIRTUAL:WWW.XXX.ZZZ:ENV]
environment variables
[VIRTUAL:WWW.XXX.ZZZ:CGI]
CGI assignment and configuration
[VIRTUAL:WWW.XXX.ZZZ:FLT]
filter configuration

The configuration for a virtual host is similar to a server. Entries for CONNECTOR, ADDRESS, PORT, SERVICE, BACKLOG, MAXACCESS and ISOLATION omitted here.

Remote Control

[SERVER:REMOTE:BAS]

Functions for status query, restart and stop are available via the configurable Telnet remote access. Server as well client is included in Devwex and are configured here.
Parameter
Value
Description
CONNECTOR
...
as connector to use Java class
ADDRESS
AUTO|LOCALHOST|IP|NAME
local address of the Servers, AUTO uses all in the system applicable IP addresses
PORT
...
local server port

Remote access for server control is via telnet. Most operating systems already contain the appropriate client can use the console (shell/command prompt). Alternatively, a corresponding client is included in Devwex.
Comamnd
Description
state
shows the starting and current time and all running servers
restart
ends all active servers and restarts with the given configuration
stop
terminates Devwex with all running servers

Example, using the Telnet client

telnet 127.0.0.1 25000   
                         
STATE                    
VERS: 1.2013.0707       
                         
TIME: 2013-07-07 06:00:00
TIUP: 2013-07-07 06:00:00
                         
SERV: TCP 127.0.0.1:25000
SERV: TCP 127.0.0.1:80   
SERV: TCP 127.0.0.1:443  

When using the Devwex client, the connection data from the server configuration devwex.ini loaded, which must be in the working directory.

Example, using the Devwex client with the startup script in Windows

devwex.bat state         
                         
VERS: 1.2013.0707       
                         
TIME: 2013-07-07 06:00:00
TIUP: 2013-07-07 06:00:00
                         
SERV: TCP 127.0.0.1:25000
SERV: TCP 127.0.0.1:80   
SERV: TCP 127.0.0.1:443  

Example, using the Devwex client with the startup script in Unix/Linux

devwex.sh state          
                         
VERS: 1.2013.0707       
                         
TIME: 2013-07-07 06:00:00
TIUP: 2013-07-07 06:00:00
                         
SERV: TCP 127.0.0.1:25000
SERV: TCP 127.0.0.1:80   
SERV: TCP 127.0.0.1:443  

Example, using the Devwex client in Java

java -cp devwex.jar com.seanox.devwex.Service state
                                                   
VERS: 1.2013.0707                                 
                                                   
TIME: 2013-07-07 06:00:00
TIUP: 2013-07-07 06:00:00
                                                   
SERV: TCP 127.0.0.1:25000                          
SERV: TCP 127.0.0.1:80                             
SERV: TCP 127.0.0.1:443                            

Server Configuration

[SERVER|VIRTUAL:X:BAS]

This section contains the general configuration for the servers and virtual hosts. Both configurations are similar to each other but the parameter CONNECTOR, ADDRESS, PORT, SERVICE BACKLOG, MAXACCESS and ISOLATION are not used for virtual hosts.
Parameter
Value
Description
CONNECTOR
...
as connector to use Java class
ADDRESS
AUTO|LOCALHOST|IP|NAME
local address of the Servers, AUTO uses all in the system applicable IP addresses
PORT
...
local server port
SERVICE
...
modul defintion for request processing
IDENTITY
ON|OFF
option for the transfer of server name with the CGI and the response
MAXACCESS
100
maximum number of parallel connections
BACKLOG
500
maximum number of deferred connections when the number of concurrent connections is reached
ISOLATION
250
maximum idle time in milliseconds to establish a connection
BLOCKSIZE
65535
maximum size of data blocks in data transfer in bytes
INTERRUPT
10
duration of interruption for system processes in milliseconds
TIMEOUT
30000
maximum idle time in milliseconds of data stream that trigger when crossing a timeout, with [S] (strictly) the limits of short term effect on outgoing server data streams, the value of 0 ignores the timeout
DURATION
500000
maximum duration of (D)CGI processes in milliseconds, when crossing the process is terminated by the server, the value of 0 ignores the term
SLICING
15000
maximum duration for initiation of request in milliseconds, when crossing the request is aborted, the value of 0 ignores the duration
METHODS
GET POST HEAD OPTIONS PUT DELETE ...
allowed methods for the server, separated by spaces
ACCESSLOG
../system/access.log
file to register of access, without specifying the standard I/O is used with OFF, the logging is disabled
SYSROOT
../system
path of system files
DOCROOT
../documents
path of web documents
INDEX
ON|OFF
option for listing of directories, the extension [S] suppresses indicates from hidden system files
MIMETYPE
application/octet-stream
standard mimetype, will be used if demanded mimetype is not in the mimetype list (section [MIMETYPES])
DEFAULT
index.htm index.html ...
standard document for directory calls, separated by spaces

Tip - In the filename of access protocols, some symbols of the time are supported. The information is given in brackets.

i.e. ACCESSLOG = ../system/access.[yyyy.MMdd].log

List of symbols to formatting the time (US Standard).
Symbol
Description
Data type
Example value
G
era designator
text
AD
y
year
numeric
1998
M
month in year
numeric
7
MM
month in year with 0
numeric
07
MMM
month in year short
text
Sep
MMMM
month in year long
text
September
d
day in month
numeric
26
h
hour in am/pm (1-12)
numeric
9
H
hour in day (0-23)
numeric
0
m
minute in hour
numeric
13
s
second in minute
numeric
22
S
millisecond
numeric
257
E
day in week short
text
Wed
EEEE
day in week long
text
Wednesday
D
day in year
numeric
304
F
day of week in month
numeric
3
w
week in year
numeric
12
W
week in month
numeric
3
a
am/pm marker
text
AM
k
hour in day (1-24)
numeric
24
K
hour in am/pm (0-11)
numeric
0
z
time zone
text
GMT+02:00

Secure Socket Layer / Transport Layer Security

[SERVER:X:SSL]

To secure transfer of data Secure Socket Layer (SSL) and Transport Layer Security (TLS) are supported. Certificates can be assigned individually and groupwise or global, for the physical hosts.
Parameter
Value
Description
PROTOCOL
TLS|SSL|...
protocol, SSL Secure Socket Layer, TLS Transport Layer Security, standard if nothing else set is TLS
ALGORITHM
SunX509|...
encryption algorithm, standard if nothing else set is SunX509
CLIENTAUTH
ON|OFF
ON activates the client authorization, standard if not set is OFF
STORE
...
path of keystore file
TYPE
JKS|...
type of keystores, standard if not set set is JKS
PASSWORD
...
password for keystore

The Java Secure Socket Extension (JSSE) is used for SSL and TLS. Since Java version 1.4.0 this extension is a part of Java Runtime Environment (JRE) or Java Development Environment (JDK).

Creating a certificate in the keystore.

./java/bin/keytool -genkey -keyalg RSA -validity 365                     
                   -alias devwex -dname "CN=127.0.0.1, C=DE"             
                   -keystore keystore -keypass default -storepass default

Without a target directory over option -keystore the keytool will be created the certificate as .keystore file in the user home directory. Depending on the operating system different user directories are used. i.e. c:\documents and properties\[user]\.keystore for Windows 2000/XP or /home/[benutzer]/.keystore for Unix based systems.

The generated keystore file can be renamed and moved to another location.

Configuration and using certificates, with the keystore file located in the Devwex working directory ./devwex/program and the JSSE available. The port can be chosen, 443 is the standard port for HTTPS.

[SERVER:X:BAS]         
  PORT       = 443     
  ...                  
                       
[SERVER:X:SSL]         
  PROTOCOL   = TLS     
  ALGORITHM  = SunX509 
  CLIENTAUTH = OFF     
                       
  STORE      = keystore
  TYPE       = JKS     
  PASSWORD   = default 
  ...                  

Due to automatically set standard values the following configuration is sufficient in most cases.

[SERVER:X:BAS]         
  PORT       = 443     
  ...                  
                       
[SERVER:X:SSL]         
  STORE      = keystore
  PASSWORD   = default 
  ...                  

Virtual Directories

[SERVER|VIRTUAL:X:REF]

Virtual directories are aliases for physical directories of file system. These can be built independently of the source directory structure, new or existing structures can be changed.

Syntax for building virtual directories

NAME = VIRTUAL > PHYSICAL [OPTION]
Option
Description
[A]
Absolute - Defines a virtual subpath points to physical directories and files. Begins the path of a request to that virtual partial path is used so defined resource. Is this a script or module, it can evaluate and use the extra path information.
[C]
Forbidden - This option denies access to virtual and physical directory and files.
[R]
Redirect - Sets a automatically redirection to a specified address for virtual and physical directories and files.
[M]
Module - Defines a virtual subpath points to modules. Begins the path of a request to that virtual partial path is used so defined module. This allows HTTP moduls integrate as a web applications. Moduls can evaluate and use the extra path information.
[X]
Extension - Only in conjunction with option [M] use the module can be expanded, so then all the requested HTTP methods are independent of the server parameter METHODS passed on to the module. This option is useful if a module extends the existing HTTP methods.
[D]
Uses the Digest Access Authentication, if an ACC record was specified.
[ACC:...]
Basic / Digest Access Authentication - Optional indication for a access list entry (ACC).
[REALM:...]
Basic / Digest Access Authentication - Optional indication of description for protected area.

Examples for using the virtual directory

DIRECTION:A = /system > ../system

the physical directory ../system will be used for the requested directory /system
DIRECTION:B = /doc > ../documents [A]

for the following requests /documents, /documentation, /doc/test.cgi?cmd=123, the physical directory ../documents will be used without naming a certain file
DIRECTION:C = /test > http://www.xxx.zzz [R]

the request to the directory /test will be redirected to http://www.xxx.zzz
DIRECTION:D = /control > example.Connector [M]

with requesting the directory /control, the class Connector of the Packages example, which is defined in the classpath of the server, is executed as module
DIRECTION:E = /program [C]

access to the requested directory /program will be denied

System References

[SERVER|VIRTUAL:X:REF]

System references are references to resources that are used by the server. These can be set here or redirect.

Syntax for building system references

SYSTEM:NAME = REFERENCE [OPTION]
Option
Beschreibung
[R]
Redirection - This option indicates an automatic redirection. This is available for all status codes except 302.

Example for using the system references

SYSTEM:INDEX = ../service/directory.html

as template to generate the listing of a folder will be ../service/directory.html used
SYSTEM:404   = ../service/error.404.html

as template to generating the status information 404 will be ../service/error.404.html used
SYSTEM:404   = http://www.xxx.zzz/404.php [R]

in case status 404 occurs a redirection to address http://www.xxx.zzz/404.php will result
Tip - In all templates are the standard for the CGI environment variables available as a parameter.
Tip - In the listing of directories to the file types are assigned symbols. The symbols, which can be modified and expanded, be summarized as a library in a GIF file, Base64 encoded, in the template ./devwex/system/index.html embedded, assigned by CSS and qualify on data group, data type and extension, which are listed as CSS attributes.

Basic- / Digest- Access Authentication

[SERVER|VIRTUAL:X:ACC]

Basic Access Authentication is one of several procedures that allows a user to authenticate a Web server or a Web application.

In addition to the Basic Access Authentication, the Digest Access Authentication is supported, their use is recommended here. Unlike the Basic Access Authentication, Digest Access Authentication sends the password directly, but to prevent reconstruction only in the form of a checksum or a fingerprint.

The configuration of the Basic / Digest Access Authentication is optional to a virtual or physical path. It is a composition of one or more references to the access, the Digest Access Authentication option [D] and the optional indication of the realm. So the configuration is required in sections REF and ACC. In section REF will defined virtual path with the Basic Access Authentication, optional can specify a physical path. The access rights will defined in section ACC. Here are defined users whith passwords.

With reference [acc:none] exist a special option to quash a authorization for a path and all sub path. Shall include in the same definition more valid references, then these are ignored.

Examples for Basic Access Authentication

[SERVER:X:REF]                                                          
  ACCESS:A = /access                     [acc:group:a] [realm:Section-A]
  ACCESS:B = /access/section             [acc:group:b] [realm:Section-B]
  ACCESS:C = /access/section/protected   [acc:group:c] [realm:Section-C]
  ACCESS:N = /access/public              [acc:none]                     

  ACCESS:X = /access/example... > ... [acc:...] [acc:...] ... [realm:...] [...

Examples for Digest Access Authentication (only option [D] makes the difference)

[SERVER:X:REF]                                                              
  ACCESS:A = /access                     [acc:group:a] [realm:Section-A] [D]
  ACCESS:B = /access/section             [acc:group:b] [realm:Section-B] [D]
  ACCESS:C = /access/section/protected   [acc:group:c] [realm:Section-C] [D]
  ACCESS:N = /access/public              [acc:none]                         

  ACCESS:X = /access/example... > ... [acc:...] [acc:...] ... [realm:...] [D] [...

Examples of definition of the access

[SERVER:X:ACC]                             
  GROUP:A = ua:pa ub:pb uc:pc              
  GROUP:B = ua:pa ub:pbb                   
  GROUP:C = uc:pcc                         

  GROUP:X = user:password user:password ...

The directory /access und all subdirectories are only available to selected user via password, except for the directory /access/public and the subdirectories.
Example
Description
ACCESS:A
On the directory /access can only be used with the users "ua" and the password "pa", "ub" and the password "up" and "uc" with the password "pc" accessible. Also, access to all the subdirectories is possible for the user. With the exception of the subdirectories of /access/section and /access/section/protected.
ACCESS:B
The directory /access/section with all subdirectories can be used by the users "ua" with the password "pa" and "ub" with the password "pbb".
ACCESS:C
Access to the directory /access/section/protected is only for the user "uc" with the password "pcc".
ACCESS:N
The Basic / Digest Access Authentication for the directory /access/public is cancelled and can be accessed without login and password, subdirectories can be supplied with Basic Access Authentication.

Note - Upper and lower case are applied for proceeding users and passwords. Colon and withspaces can not be used for usernames or passwords.
Note - Basic / Digest Access Authentication can also be used for files. Some browsers can however then request new authorisation for the directory level.

Common Gateway Interfaces

[SERVER|VIRTUAL:X:CGI]

For data exchange and to connect external runtime environments and applications, the specification 1.1 of the Common Gateway Interface PHP, Perl, Python and others are supported. Optional FastCGI is also available.

Optional with DCGI further leaning to the CGI interface to access external applications and runtime environments is available. Basic Principle of operation correspond to the CGI. Also communication from the DCGI via standard I/O and the server relevant information is transmitted as environment variables. For environment variables is however different than the way of communication. These are passed to the CGI when calling the external application or runtime environment as a system or environment variable. Not so with the DCGI, here are the environment variables are part of a stream. Thus, the data stream from the DCGI begins with the control character sequence 0x07 0x07, then the following environment variables to the first occurrence of control character 0x01. From here, the typical for the CGI request body is transferred.

The advantage of DCGI is the easy transfer of environment variables. Thus, systems and environments can also be used which possess no exclusive environment or have no access to the environment from the operating system.

Example for DCGI-Requests

[0x07][0x07]                                       
SERVER_PORT=80                                     
SERVER_PROTOCOL=HTTP/1.0                           
SERVER_SOFTWARE=Seanox-Devwex/1.2013.0707
CONTENT_LENGTH=7                                   
REQUEST_METHOD=POST                                
...                                                
[0x01]Test...                                      

Syntax for using the Common Gateway Interfaces

FILE EXTENSION = METHODS > APPLICATION [OPTION]

Overview of the available options
Option
Example value
Description
[I]
-
uses DCGI
[C]
.../applications/test.cgi
full path including file name and file extension
[P]
.../applications/
path
[F]
test
file name without extension
[E]
.cgi
extension

Examples for the configuration of the Common Gateway Interfaces

CGI = POST GET > c:/example

application example will be started, the path of the script file has been set in the environment variable, the path to script file is here passed over environment variables SCRIPT_FILENAME and PATH_TRANSLATED
CGI = POST GET > c:/example [C]

application example will be started, the path of the script file will be given as argument, the path to script file is passed to application here as start argument
CGI = POST GET > c:/example [I]

application example will be started by using DCGI, the path to script file is here passed over environment variables SCRIPT_FILENAME and PATH_TRANSLATED

Examples for using PHP, Perl, Java und native web applications

PHP = POST GET > c:/php/php.exe

file extension php will be assigned to PHP as executing CGI application
CGI = POST GET > c:/perl/bin/perl.exe [C]

file extension perl will be assigned to Perl as executing CGI application
JAR = POST GET > java -jar [P][F].jar [I]

file extension jar will be assigned to Java as executing CGI application
JAR = POST GET > java -jar [C] [I]

file extension jar will be assigned to Java as executing CGI application
EXE = POST GET > [C] [I]

file extension exe is defined as executing DCGI application
EXE = POST GET > [C]

file extension exe is definded as executing CGI application

Example for the usage of modules

SSX = POST GET > com.seanox.ssx.Connector [M]

file extension ssx will be assigned to module com.seanox.ssx.Connector located in the classpath

Overview of supply environment variables (selection)
Environment variables
Example value
Description
CONTENT_LENGTH
1000
quantity of with the request Body transmitted data in bytes
CONTENT_TYPE
text/plain
with the request passed MIME type for data
DOCUMENT_ROOT
.../devwex/documents
physical path from the root directory of web documents
GATEWAY_INTERFACE
CGI/1.1
from server supported version of CGI interface
HTTP_ACCEPT
*/*
with the request submitted list of MIME types, which is supported by the client
HTTP_ACCEPT_ENCODING
gzip, deflate
with the request submitted list of encoding methods, which is supported by the client
HTTP_ACCEPT_LANGUAGE
de
with the request submitted list of languages, which is supported by the client
HTTP_CONNECTION
Keep-Alive
with the request submitted information on status of HTTP connection between server and client
HTTP_HOST
experimental.seanox.com
with the request submitted domain name or IP address of the from client requested destination
HTTP_USER_AGENT
Mozilla/4.0 (compatible; ...)
with the request submitted product and version informations of the client
MODULE_OPTS
...ssi.Connector [allow:all] [M]
information on called module with all parameters
PATH
...
general list of paths to search for resources and applications, optionally set on [SERVER:X:ENV]
PATH_ABSOLUTE
/example.ssi
real path for URL on absolute paths
PATH_BASE
/example.ssi/folder/...
complete path of URL
PATH_INFO
/folder/...
advanced path of URL on absolute paths
PATH_TRANSLATED
.../devwex/documents/example.ssi
physical location of requested resource in file system
QUERY_STRING
parameter=name
list of the request URI parameters
REMOTE_ADDR
sirius.seanox.com
name or IP address of calling client
REMOTE_PORT
1573
port of calling client
REQUEST_METHOD
POST
with the request submitted HTTP request method
REQUEST_URI
/example.ssi/...?parameter=name
with the request submitted HTTP request path, including transmitted parameters
SCRIPT_FILENAME
.../devwex/documents/example.ssi
physical path of requested resource in file system
SCRIPT_NAME
/example.ssi/...
HTTP path of requested resource
SCRIPT_URI
http://...seanox.com/example.ssi/...
complete HTTP path of requested resource
SCRIPT_URL
/example.ssi
relative HTTP path of requested resource
SERVER_NAME
experimental.seanox.com
name or IP address of the server on the network
SERVER_PORT
80
equipped port of the server
SERVER_PROTOCOL
HTTP/1.0
from server supported version of HTTP protocol
SERVER_SOFTWARE
Seanox-Devwex/...
product name of the installed server software
SYSTEMDRIVE
C:
general indication of the drive of operating system, optionally set on [SERVER:X:ENV] for microsoft windows
SYSTEMROOT
C:\WINDOWS
general indication of the path of operating system, optionally set on [SERVER:X:ENV] for microsoft windows
UNIQUE_ID
FEK2VFTY26DHI584C5
on request related unique identification number

Tip - Ends in the configuration file a parameter or a value with [+], used the full contents of a line.

i.e. PATH     = ./documents;./libraries;./system [+]
     PATH [+] = ./documents;./libraries;./system    
Tip - The working directory of CGI applications equals the Devwex working directory. So if Ini- files i.e. php.ini are used they should be found in the same directory.
Tip - To install PHP, the configuration file php.ini stored in the working directory of Devwex or PHP the path to the startup parameters -c are indicated. Since version 4.x of PHP are the entries cgi.rfc2616_headers = 1 for correct operation of the PHP function header(); and for security execution cgi.force_redirect = 0 and cgi.redirect_status_env = 302 required. Alternatively, you can put in section [SERVER:X:ENV] to configuration file devwex.ini, the entry REDIRECT_STATUS = 302.
Tip - CGI and DCGI application and scripts can be used in all DOCROOT directories. A special CGI-BIN directory is not necessary.
Tip - Executable Windows binaries (*.exe, *.com) can be used with a different file extension under windows. If i.e. CGI or DCGI applications are used as Windows binary (*.exe or *.com) without configuring these file extensions for CGI or DCGI applications, file extensions can be chosen. Example example.exe is renamed to example.cgi, the referring entry in the configuration file looks like: CGI = POST GET > [C]
Tip - The method entry ALL will proceed all incoming methods.

Environment Variables

[SERVER|VIRTUAL:X:ENV]

Environment variables provide external applications and runtime environments essential and additional information about the operating system.

As an extension of server environment variables are defined in this section for CGI and DCGI additional required environment variables.

Syntax for building environment variables

PARAMETER = VALUE

Examples for the configuration of environment variables

WEBSERVER = DEVWEX

environment variables WEBSERVER is set with value DEVWEX
Note - CGI applications to determine system resources, e.g. for database or network, usually on the environment. Thus, these environment variables like PATH, SYSTEMDRIVE, SYSTEMROOT and for PHP REDIRECT_STATUS = 302 should be set in the configuration file devwex.ini. Environment variables without value will not be considered.
Tip - With option [?] at end of a parameter, this a dynamic value can be assigned, which is set at startup as a start arguments or system properties. This allows systemically environment variables, e.g. PATH, SYSTEMDRIVE or SYSTEMROOT are for Windows, passed dynamically. Please find more informations in the configuration file section.

Filters

[SERVER|VIRTUAL:X:FLT]

Accesses to servers and virtual hosts can be controlled by individually defined rules. Incoming requests are handled before processing. Custom error pages and redirects are supported.

Syntax for using filters

NAME = METHOD CONDITION FUNCTION PARAMETER VALUE [A] ... > REFERENCE [R]

A specification of a reference is optional for filter definitions.
Name
Value
Description
NAME
...
can be chosen
METHOD
GET|POST|PUT|ALL|...
HTTP method to be reacted
CONDITION
IS|NOT|ALWAYS
condition for filtering
FUNCTION
STARTS|EQUALS|CONTAINS|ENDS|EMPTY
method for comparing the values
PARAMETER
...
parameter to be tested
VALUE
...
value to be checked
OPTION
[A]
logical AND-conditions - The logical combination of several conditions.
[R]
Redirection - Refers to a corresponding address and initiate a redirection. An error page is not supported.
[M]
Module - This option is referred to an HTTP module. The call of modules is not a final step. A stopping of filter sequence takes place only when a module changes the status or response data sends to the client.

For the filter function are all contained in the header of the request fields, and some advanced parameters and the environment variables from the CGI environment available. Usage of parameters, fields and values are not case sensitive.

Example for a request

GET /directory/file.cgi?value=123 HTTP/1.1
Accept-Encoding: gzip, deflate            
Accept-Language: de                       
Accept: */*                               
User-Agent: Browser                       
Host: www.xxx.zzz                         

Parameters and values are dependent on the content of the request header. Filters will not read the request body, which parameters such as the HTTP method POST is passed in the body, are not available.
Parameter
Value
Description
REQUEST
GET /directory/file.cgi?value=123 HTTP/1.1
request
METHOD
GET
HTTP method
PATH
/directory/file.cgi
path of request
QUERY
value=123
query
PROTOCOL
HTTP
protocol
VERSION
1.1
version of protocol

Examples for filtering

FILTER-A = GET NOT EQUALS ACCEPT-LANGUAGE EN

method GET will be denied, if the field of request header Accept-Language does not equal EN
FILTER-B = GET NOT CONTAINS ACCEPT-LANGUAGE EN

method GET will be denied, if the field of request header Accept-language does not contain EN
FILTER-C = GET IS EQUALS ACCEPT-LANGUAGE EN

method GET will be denied, if the field of request header Accept-Language equals EN
FILTER-D = GET IS CONTAINS ACCEPT-LANGUAGE EN

method GET will be denied, if the field of request header Accept-Language contains EN
FILTER-E = GET IS STARTS REMOTE_ADDR 192.168.

method GET will be denied, if the CGI parameter REMOTE_ADDR starts with 192.168.
FILTER-F = GET IS ENDS SCRIPT_URL .dat

method GET will be denied, if the CGI parameter SCRIPT_URL ends with .dat
FILTER-G = GET IS CONTAINS PATH /documents [A] GET IS EMPTY REFERER

method GET will be denied, if the request parameter PATH contains /documents and the field of request header Referrer is empty
FILTER-H = GET IS CONTAINS PATH /private > ../system/error.403.html

method GET will be denied, if the requesz parameter PATH contains /private, template for generating the status information 404 will be the file ../system/error.403.html
FILTER-I = GET IS CONTAINS PATH /private > http://www.xxx.zzz/403.php [R]

contains parameter PATH in the request header /private, method GET will be forwarded to address http://www.xxx.zzz/403.php
FILTER-J = GET IS ENDS PATH .do > example.Connector [A:...] [B:...] [M]

method GET will be executed the module Connector with the additional parameters A and B, which is located in the server classpath
FILTER-K = ALL ALWAXS > example.Connector [A:...] [B:...] [M]

with all requests will be executed the module Connector with the additional parameters A and B, which is located in the server classpath

Statuscodes

[STATUSCODES]

HTTP requests are always answered by the server with a status code. So that the client is informed whether the request was successfully processed, an error has occurred or where or how the desired information is reached. In addition to the status code also a status text is sent. This optional text here defined for each status code. Defaults are not implemented in Devwex. The information is global and is therefore used by all servers and virtual host.

Syntax for building status codes

CODE = TEXT

Example for declaring the status codes

200 = Success

response header
HTTP/1.0 200 Success
404 = Document Not Found

response header
HTTP/1.0 404 Document Not Found

Mimetypes

[MIMETYPES]

MIME type (Multipurpose Internet Mail Extensions), also Content-Type or Internet Media Type, classifies the information with the server response data. Data types are here corresponding media types and subtypes assigned. Defaults are not implemented in Devwex. The information is global, separated by spaces and is thus used by all servers and virtual host.

Syntax for building mimetypes

MIMETYPE = FILE-EXTENSION FILE-EXTENSION ...

Example for assigning mimetypes

application/octet-stream = com exe class

files with the extensions *.com, *.exe and *.class will be assigned to the mimetype application/octet-stream
Seanox Software Solutions since 1996
Advanced Server Developing SEANOXDEVWEX