The FastCGI External Server appendix is essential reading before configuring a FastCGI External Server.

Configuration File

All options, except for the configuration file name, can be set in a configuration file. One advantage of using a configuration file is that the file can be changed, and the changes will apply when the server is restarted.

The default location for the configuration file is the /axes/configs directory. You can edit the default W3 configuration file using the command:

EDTF STMF(‘/axes/configs/aXesW3.conf’)

The configuration file is a simple text file containing a series of ‘option’ or ‘option=value’ directives separated by white space. Valid directives are described below.

Comments may be placed anywhere within the configuration file. Comments begin with the hash ('#') character; all characters after the # are ignored.

Long lines can be continued by breaking them with a trailing backslash (‘\’).

Most aXes-W3 configuration directives have reasonable defaults and need not be specified.

When specifying numeric values do not include leading zeroes because these will cause the value to be interpreted as an Octal number (i.e., 037 will be interpreted as decimal 31).

Configuration Directives

Default values are either underlined or explicitly stated.

Mandatory parameters are marked with an asterisk *.

AdminPath

Specifies the directory where the aXes Application Server Administration JavaScript and XSL files reside. There are no constraints on the name of this directory.

The default is a directory named <server-root>/Admin

where <server-root> is the root directory of the aXes Application server.

AGILimit

Specifies the time limit, in seconds, for AGI processes to return a response.

The default value is 30.

AGIPattern

Specifies the legal set of URL patterns for AGI and therefore CGI programs. Multiple patterns are separated with a bar '|'. An asterisk '*' matches any number of characters in a component, '**' matches any number of characters in any number of components, '?' matches any character. The default pattern stipulates that AGI or CGI programs must be in the URL /agi, or /anydir/agi or /anydir/anydir/agi, or the name must end with '.CGI'. CGI is disabled if '**.CGI' is removed from the pattern. AGI, and by implication CGI, is disabled by setting the pattern to a nonexistent URL.

The default value is: (/agi/**|/*/agi/*|/*/*/agi/*|/**.cgi)

CERNLog

Specifies that CERN logging is active. Allowable values are 0 or 1. Zero (0) disables CERN logging and 1 enables CERN logging.

The default value is 0.

When set to 1 the LogPath directive must also be specified.

CGILuaScript

Specifies that CGI is implemented via AGI. The provided Lua script agi/cgi.lua implements CGI. If you wish use an alternative script you may change this name. Rename or delete the stream file agi/cgi.lua to permanently disable CGI.

The default value is (agi/cgi.lua)

Host

Specifies the hostname or IP address of the interface to which the server will bind. If this directive is not specified the server will bind to all available addresses.

Refer to the Multi-homing section for more information.

Library

Specifies the IBM i library name for aXes objects such as data queues.

This defaults to the product installation library, if this is not found it then defaults to ‘AXES’.

LogPath

Specifies the name of the directory to be used for CERN logs and server trace files.

There is no default value.

This directory is secured with an Access Control List upon creation. Log files are written in the code page specified by the Codepage directive. This directive is required when the CERNLog or Trace directive is enabled.

Path

Specifies the PATH used for invocation of any external processes such as CGI programs.

The default path is (/usr/bin:%LIBL%)

PersistenceThreshold

Specifies the maximum number of persistent connections that aXes Application Server will support. Connections in excess of this number will be treated as non-persistent connections.

The default value is 0.

PersistenceLimit

Specifies the server side time limit, in seconds, for persistent connections.

The default value is 0.

Port

Specifies an alternate TCP/IP port number on which to listen.

The default port number is 80.

This directive is equivalent to the PORT keyword on the STRAXESW3 command.

If you need to alter your aXes installation to use a port number other than the default of 80 then there are some port numbers you probably should not choose because some web browsers have a list of port numbers they will block by default.

If you use a port number that your web browser blocks by default you will need to alter your web browser configuration to allow it.

There are 65535 port numbers available. Only a very small number are blocked by web browser default configurations – you should try to avoid these numbers so you don’t have to alter your browser configuration.

Your best choice is any port number:

  • Greater than 1023
  • Not listed in the Wikipedia list (eg: 8085) or listed in the Wikipedia list with Status = Unofficial (eg: 8081)

Wikipedia has a list of well known and registered ports: http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers

The Wikipedia list is far longer than the list of ports that are blocked by any of the default web browser configurations.

IANA also has a list of ports: http://www.iana.org/assignments/port-numbers

PostLimit

Specifies the maximum number of bytes that may be sent to the server with a POST transaction.

The default value is 5000.

When using eXtensions you should set this value to 12000.

ServerRoot

Specifies a directory that is the ‘root’ directory for aXes Application Server. This value is used as the ServerRoot from which URLs are mapped to files. It restricts aXes Application Server to serving files that exist in the directory tree starting from the specified directory. This directive is equivalent to the SVRDIR keyword on the STRAXESW3 command.

The default value is the product installation directory.

SSLAppID

Specifies a character string, of up to 100 characters, representing the registered SSL application identifier. If SSLPort is specified you must specify this directive.

There is no default value.

SSLOnly

Specifies whether clients must connect using Secure Sockets Layer (SSL). Allowable values are 0 or 1. Zero (0) disables SSL Only and 1 enables SSL Only.

The default value is 0.

When SSLOnly is enabled (set to 1) the aXes Application Server will ignore the Port value and start the server with SSL support. The SSLAppID must be specified and SSLPort must also be specified. This allows the aXes Application Server to be started using the SSL protocol only, which creates a very secure server. Using SSLOnly you could use multiple application servers. One aXes Application Server instance could be listening for non-secure requests on port 80 while another instance listens on port 443. This allows you to spread the SSL encryption workload to a separate process.

SSLPort

Specifies a TCP/IP port number to listen on. The normal value for this port is 443. If this entry is not specified then SSL support is disabled. If you specify an SSL port you must also specify either SSLAppID.

There is no default value.

Trace

Specifies whether server tracing is active. Allowable values are 0 or 1. Zero (0) disables server tracing and 1 enables server tracing.

The default value is 0.

When set to 1 the LogPath directive must also be specified. A diagnostic trace is written to the <log-path>/.aXesW3trc.txt file.

TraceLevel=option-list

Specifies the level of trace information written to the trace log. The option-list is a space-separated list containing at least one of the following keywords:

Value

Description

Info When specified Informational messages will be logged to the IBM i job log and the trace file (if enabled). The default is that these messages are not logged.
Error When specified Error messages will be logged to the IBM i job log and the trace file (if enabled). The default is that these messages are not logged.
Warn When specified Warning messages will be logged to the IBM i job log and the trace file (if enabled). The default is that these messages are not logged.
Debug When specified Debugging messages will be logged to the trace file (if enabled). The default is that these messages are not logged.

FastCGI Directives

The FastCGI External Server appendix is essential reading before configuring a FastCGI External Server.

FastCgiIpcDir=(/tmp/fcgi)

Specifies the directory used for inter-process communication. This directory is used to contain the Unix domain sockets that are used for communication between the FastCGI applications and the application server. If the directory path does not begin with a slash (/) then it is presumed to be relative to the ServerRoot. If the directory doesn't exist it will be created with appropriate authorities. The directory path must be on a local file system. If you use the default directory, or another directory within /tmp, aXes Application Server will fail if your system periodically deletes files from /tmp.

This directive must precede any FastCgiServer or FastCgiExternalServer directives (which make use of Unix sockets). The application server user profile must have read (*R), write (*W), and execute (*X) permissions to the directory path, but otherwise should not be accessible to anyone.

FastCgiIpcDir is typically used move the directory some where more suitable than the default for the platform or to prevent multiple aXes Application Server instances from sharing FastCGI application servers.

FastCgiServer

This directive defines an internal FastCGI server. It has the following form:

FastCgiServer urlname –program name [option-list]

Specifies the URL and program that defines the internal FastCGI application. If the Urlname does not begin with a slash (/) then it is presumed to be relative to the ServerRoot. The URL is the identifier for the FastCGI application. The application server will pass client requests that begin with this URL to the specified FastCGI application.

FastCgiServer Switches

Switches are not case-sensitive and can be one of the following:

Required switches:

program name

Specifies the name of the IBM i FastCGI program that will be started as a Batch Immediate (BCI) job. The name can be a fully qualified name using the IFS naming format. If parameters are passed to this program then an additional level of quotation marks may be required. For example:

program "AXESTS.PGM /axescfg/ts.conf"
Program '/QSYS.LIB/AXES.LIB/ECHO.PGM'
PROGRAM 'ACCOUNTS.PGM "parameter with spaces"'

Optional switches:

-appConnTimeout n (0 seconds)

Specifies the number of seconds to wait for a connection to the FastCGI application to complete or 0 to indicate that a blocking connect() should be used. Blocking connections have an OS dependent internal timeout. If the timeout expires, a server error results. For non-zero values, this is the amount of time used in a select() call to write to the file descriptor returned by a non-blocking connect(). Non-blocking connections may be troublesome on many platforms. See the -idle-timeout option which produces similar results but in a more portable manner.

-authpath name[=pattern]

Specifies a path where aXes Application Server will look for an Access Control List. The ACL will control authorized access to this FastCGI application.

-clientstderr (none)

Specifies that data written to stderr will be written to the client browser, however it will be always written to the aXes-W3 log.

-flush (none)

Specifies that data received from the application will be forced to the client as it is received. The default behaviour is for the application server to buffer data until all application data is received and then send it to the client, which results in better throughput.

-idle-timeout n (30 seconds)

Specifies the number of seconds of FastCGI application inactivity allowed before the request is ended and the event is logged — depending on the current TraceLevel. The inactivity timer applies only as long as a connection is pending with the FastCGI application. If a request is queued to an application, but the application doesn't respond (by writing and flushing) within this period, the request will be ended. If communication is complete with the application but incomplete with the client (the response is buffered), the timeout does not apply.

-initial-env name=value (none)

Specifies a name=value pair representing an environment variable which is passed in the FastCGI application's initial environment. The option can be repeated for a maximum of 64 name=value pairs.

-jobname name

Specifies the simple job name to use for the submitted job. If this option is not provided the job name will be the same as the aXes-W3 job. For example:

"-Jobname AXESTS"

-kill n (10)

Specifies the number of seconds to allow for an aXes Application Server started FastCGI application to end. If this number is zero aXes Application Server will not end the application when it exits.

-listen-queue-depth n (100)

Specifies the depth of the listen() queue, also known as the backlog, shared by all of the instances of this application. A deeper listen queue allows the server to cope with a temporary connection increase by allowing the TCP/IP stack to queue excess requests; it does not increase throughput. Adding additional application instances may increase throughput and performance, depending upon the application and the host.

-mt (none)

Specifies that the application is started as a multithreaded enabled application.

-pass-header header (none)

Specifies the name of an HTTP Request Header to be passed in the request environment. This option makes available the contents of headers that are normally not available to a CGI environment such as the Authorization header.

-port n (none)

Specifies the TCP port number (1-65535) the application will use for communication with the application server. This option makes the application accessible from remote systems in the network as well as the local system. The -socket and -port options are mutually exclusive.

-processes n (1)

Specifies the number of instances of the application to start during server initialization.

For aXes Terminal Server, this value is restricted to 1.

-socket filename (generated)

Specifies the filename of the Unix domain socket that the application will use for communication with the application server. The socket is created in the directory specified by FastCgiIpDir. This option makes the application accessible to other applications on the same machine or via an external FastCGI application definition specified on the FastCgiExternalServer directive. If neither the -socket nor the -port options are specified, a Unix domain socket filename is generated. The -socket and -port options are mutually exclusive.

FastCgiExternalServer

This directive defines an external FastCGI server. It has the following forms:

  • FastCgiExternalServer urlname –host hostname:port [option-list]
  • FastCgiExternalServer urlname –socket socketname [option-list]

Specifies the URL and connection that defines the external FastCGI application. If the Urlname does not begin with a slash (/) then it is presumed to be relative to the ServerRoot. The URL is the identifier for the FastCGI application. The application server will pass client requests that begin with this URL to the specified FastCGI application

External FastCGI applications are not started by aXes Application Server, they are presumed to be started and managed separately. The aXes samples contain the source for a command called Submit FastCGI Job (SBMFCGIJOB) that can be used for starting FastCGI applications independent of the server. Applications can also be self-starting and information regarding this can be found in the FastCGI development kit at http://www.fastcgi.com. External FastCGI applications may be shared between application servers across a network. Use external FastCGI when you need to start and stop the application server without starting or stopping the application, or for example when sharing an aXes Terminal Server between Apache and aXes Application Server.

FastCgiExternalServer Switches

Switches are not case-sensitive and can be one of the following:

Required switches:

-host hostname:port (none)

The hostname or IP address and TCP port number (1-65535) the application uses for communication with the web server. This option makes the application accessible to other applications on the same system and also on remote systems. You may omit the hostname part if you want the server to accept requests on any IP address recognized by the local system. The -socket and -host options are mutually exclusive and one of them must be specified.

-socket filename (generated)

Specifies the filename of the Unix domain socket that the application will use for communication with the web server. The socket filename is relative to the directory specified by FastCgiIpDir. This option restricts application accessibility to other applications on the same system. The -socket and -host options are mutually exclusive and one of them must be specified.

Optional switches:

-appConnTimeout n (0 seconds)

Specifies the number of seconds to wait for a connection to the FastCGI application to complete or 0 to indicate that a blocking connect() should be used. Blocking connection have an OS dependent internal timeout. If the timeout expires, a server error results. For non-zero values, this is the amount of time used in a select() call to write to the file descriptor returned by a non-blocking connect(). Non-blocking connection may be troublesome on many platforms. See the -idle-timeout option which produces similar results but in a more portable manner.

-authpath name[=pattern]

Specifies a path where aXes Application Server will look for an Access Control List. The ACL will control authorized access to this FastCGI application.

-clientstderr (none)

Specifies that data written to stderr will be written to the client browser, however it will be always written to the aXes-W3 log.

-flush (none)

Specifies that data received from the application will be forced to the client as it is received. The default behaviour is for the web server to buffer data until all application data is received and then send it to the client, which results in better throughput.

-idle-timeout n (30 seconds)

Specifies the number of seconds of FastCGI application inactivity allowed before the request is ended and the event is logged — depending on the current TraceLevel. The inactivity timer applies only as long as a connection is pending with the FastCGI application. If a request is queued to an application, but the application doesn't respond (by writing and flushing) within this period, the request will be ended. If communication is complete with the application but incomplete with the client (the response is buffered), the timeout does not apply.

-pass-header header (none)

Specifies the name of an HTTP Request Header to be passed in the request environment. This option makes available the contents of headers that are normally not available to a CGI environment such as the Authorization header.

For example:

FastCGIExternalServer “/rmtecho” –appConnTimeout 30-idle-timeout 30 –socket rmtecho

CompressList Section


This section is prefaced by the CompressList tag and entries in this section specify the file types that will be compressed. These entries are equivalent to the file extension without the dot separator. If a CompressList section does not exist in the configuration file then the server automatically compresses the following types:

css

dat

doc

htm

html

js

log

man

mime

mjs

ppt

tar

text

txt

xml

xsl

The existence of a CompressList section in the configuration file will override the default values.

MimeTypes Section

This section is prefaced by the MimeTypes tag and defines the mime types for the HTTP Content-Type: header.

If there is no matching mime type for the document it is transmitted as ‘text/plain; charset=...’

If a MimeTypes section does not exist in the configuration file then the server uses the following default values:

html,text/html; charset=%s

htm,text/html; charset=%s

txt,text/plain; charset=%s

rtx,text/richtext

etx,text/x-setext

tsv,text/tab-separated-values

css,text/css

xml,text/xml

dtd,text/xml

gif,image/gif

jpg,image/jpeg

jpeg,image/jpeg

jpe,image/jpeg

png,image/png

js,application/x-javascript

mjs,application/x-javascript

The %s of the charset is replaced with the character set name of the configured code page. The default character set is ISO-8859-1. The existence of a MimeTypes section in the configuration file will override the default values.

URLMap Section

aXesW3 does not support symbolic links; instead it offers URL mapping. URL mapping allows you to hide file system information by mapping virtual URLs to an associated IFS path name. Only directories can be mapped as virtual URLs and mapped directories cannot be symbolic links. There is a limit of 100 virtual URLs per server.

This section is prefaced by UrlMap tag and each entry is of the form path=URL. The left hand side of the entry is the IFS pathname and the right hand side is URL name. If the URL name matches an existing path name within the IFS it will be ignored. For example:

/usr/testapp/e_rpg=/rpgapp

URL mapping also allows aXesW3 to serve files outside the Server Root by mapping a URL to a directory path.

Multi-homing

Multi-homing means using one machine to serve multiple hostnames. For instance, if you are an internet provider and you want to let all of your customers have customized web addresses, you might have www.joe.axes.com, www.simon.com, and your own www.axes.com, all running on the same physical hardware. This feature is also known as virtual hosts.

When a host name is not specified then the aXes Application Server will bind to any IP address that is defined for the system on which aXes Application Server is running, thus a single instance of aXes Application Server can serve requests addressed to multiple IP interfaces as long as each interface is defined on the same system.

Additional IP addresses can be defined using the ADDTCPIFC (Add TCP/IP Interface) Control Language command, or option 1 of the CFGTCP menu.

A more flexible approach would be to define separate configuration files for each web site and start a separate instance of aXes Application Server for each web site. The aXes Application Server has much lighter resource requirements than other web servers so it is less of a problem starting multiple instances of aXes Application Server. Also, it allows greater flexibility in enabling and disabling web site access, and it has improved security because a given instance of aXes Application Server cannot serve pages from a different instance.

To accomplish this you would create separate configuration files and set Host= to the IP address or domain name of the web site, set ServerRoot= to the directory containing the web site files. Then you would start a server instance for each configuration. For example:

STRAXESW3 CFG(‘/configs/widgets.conf’)

STRAXESW3 CFG(‘/configs/gadgets.conf’)

STRAXESW3 CFG(‘/configs/doodads.conf’)

Each server must either use a unique IP address or a unique port.

See Appendix A. Configuration Scenarios for more information.

Custom Errors

The aXes Application Server lets you define your own custom error pages for the various HTTP errors. There is a separate file for each error number, all stored in one special directory. The directory name is ‘errors’, at the top of the web directory tree. The error files should be named ‘errNNN.html’, where NNN is the error number. So for example, to make a custom error page for the authentication failure error, which is number 401, you would put your HTML into the file ‘errors/err401.html’. If no custom error file is found for a given error number, then the usual built-in error page is generated.

Custom error pages can be generated for any language by prefixing the error page with the IANA country code, for example. ‘frerrors/err401.html’, ‘dkerrors/err401.html’. If the browser primary language preference matches the defined page name then the appropriate page will be served. If no language match occurs then the page without a language prefix will be used.

HTTP Compression

HTTP compression provides faster transmission time between compression-enabled browsers and aXes Application Server. You can compress static files and data from applications. By default aXes Application Server uses HTTP compression for appropriate text content.

The aXes Application Server will compress data streams that are sent back to a browser. URL resources are compressed only if they are not already compressed and if their extension exists in the CompressList of extensions.

When aXes Application Server receives a request, it checks to see if the browser is compression-enabled. It then checks the file name extension to see if the requested file extension is contained within the configuration compression list, aXes Application Server then checks to see if the file has previously been requested and is already stored in a compressed format in the server cache. If the file extension is in the configuration compression list and is not already stored in a compressed format, aXes Application Server compresses it and sends the compressed file to the browser, and adds a compressed copy of the file to the server cache. If the file is stored in a compressed format, aXes Application Server sends the compressed file to the browser, and adds a compressed copy of the file to the server cache.

The cost of compressing a static file is modest and is typically incurred only once, because the file is then stored in the server cache. The cost of compressing dynamically generated files is slightly higher, because they are not stored and must be regenerated with each request. The cost of expanding the file at the browser is minimal. Compressed files download faster, so are particularly beneficial to the performance of any browser that uses a network connection with restricted bandwidth (a modem, for example).

aXes Application Server will only compress files when the browser indicates that it supports compression.

Logs

Message Queue

aXes-W3 logs the start and stop of the server and any errors to the 'AXESW3' message queue. Critical errors are also sent to the system operator’s message queue '*SYSOPR'.

aXes issues the message AXS5001 on successful start-up and AXS5002 on successful termination and AXS5003 on abnormal termination.

Job Log

The aXes-W3 job log will contain any errors that prevent the server from starting such as invalid invocation parameters, invalid configuration file, invalid configuration file contents. Critical errors are also placed in the job log.

CERN Common Log Format

The aXes Application Server can optionally log all incoming requests to a server access log file. All log files are generated using the common log file format used by many web servers. Log files are maintained in the same format as the CERN and NCSA servers. Log files in this format can be imported into one of the many log file analysis programs on the market.

Common log-file format entries are generated by aXes Application Server with the following structure:

remotehost rfc931 authuser [date] “request” status bytes

where:

Value

Description

remotehost The remote hostname, or IP address if the hostname is not available.
rfc931 The remote logname of the user.
Authuser The name supplied by the user in response to an authentication request.
[date] The date and time on which the request occurred.
“request” The request line exactly as it came from the client.
Status The HTTP status code returned to the client.
Bytes The content-length of the document transferred.
Status Status element

Status Status element

The log-file Status element is a three-digit request result code. The Status can be used by log-file analysis programs and is also returned to the client. The first digit of the Status defines the class of response. There are five values for the first digit:

1xx: Informational: Request received, continuing process

2xx: Success: The action was successfully received, understood, and accepted

3xx: Redirection: Further action must be taken in order to complete the request

4xx: Client Error: The request contains bad syntax or cannot be fulfilled

5xx: Server Error: The server failed to fulfil an apparently valid request

The individual values of the numeric status codes returned to clients by aXes Application Server are presented below. The phrases listed here are recommended phrases, they may be replaced by local equivalents. See HTTP Status Codes for more information.

"200" OK

"206" Partial Content

"302" Found

"304" Not modified

"400" Bad Request

"401" Unauthorized

"403" Forbidden

"404" Not Found

"408" Request timeout

"500" Internal Error

"501" Not Implemented

"502" Server Busy

"503" Service Temporarily Overloaded

Log files are written to the path specified on the LogDir configuration file option. If required, the creation of log files can be disabled using the configuration file option CERNLog=0 so that no logs are produced. The default is to not produce log files.

Log files are written in the code page specified in the configuration file used to start the aXes Application Server instance. Consequently, suitably authorized clients may view log files by using a browser. When log files are created, read, write, and execute (*RWX) access permissions are granted to the aXes Application Server job user profile, and PUBLIC have read (*R) access permissions. The aXes Application Server will always create an empty Access Control List in the log file directory, if an ACL does not already exist and logging is enabled. Thus no browser user or agent can view these log files unless access authority is explicitly granted by adding the user to the ACL or by deleting the ACL.

When logging is enabled, each time an instance of aXes Application Server starts it cycles past existing log files and creates a new one. All aXes Application Server created log files use the following naming convention:

cernYYYYMMMDD _HHMMSS.txt

Where:

Value

Description

YYYY 4 digit year
MMM Abbreviated month name
DD Day of the month
HH Hour in 24-hour format
MM Minutes of the hour
SS Seconds of the minute

Log file entries are cached by aXes Application Server for efficiency reasons. Consequently, log-file entries may not be written immediately to disk. Log-files are flushed periodically by aXes Application Server eliminating concurrency and synchronization lags.

Trace File

The aXes Application Server trace file, when enabled, provides a detailed trace of aXes Application Server operations. The level of detail traced is specified through configuration file directives.

Symbolic Links

The aXes Application server does not allow symbolic links. Each URL is parsed and expanded to ensure that no component of the URL contains a symbolic link. This means that to access a directory that is not subordinate to the ServerRoot directory a URL map entry must be used. This means that that aXes Application Server can serve files outside of its directory tree only if they have been explicitly defined in the URL map.

Copyrights

Copyright © LANSA Group. All rights reserved.

aXes Application Server makes use of software from the following third parties and LANSA recognizes their copyrights.

Copyright © 1995-1998 Jean-loup Gailly and Mark Adler.

Copyright © 1999,2000,2001 Mark Martinec. All rights reserved.

Copyright © 1994-2003 TeCGraf, PUC-Rio. All rights reserved.

Copyright © 1995,1998,1999,2000,2001 by Jef Poskanzer. All rights reserved.

Copyright © 1996 Open Market, Inc.