In the world wide web, Common Gateway Interface(CGI) is the basic language used to create web pages to communicate information using HTML. Because HTML can only transmit data from the server to the client, it is limited to static, one-dimensional web pages that lack user-server interaction. One method that addresses the weaknesses of HTML is the use of external programs. CGI is the interface used between external programs and web servers.

An external program is called a CGI program or a CGI script. For example, creating a guest book application that can receive comments from visitors is impossible using only HTML. This example and numerous others involving bilateral communication between client and server highlights the need for external programs. C/C++, Perl, UNIX Shell, or Tcl/Tk are common languages used to create CGI programs.

There are many CGI programs that can make a website interactive. A visitor counter, guest book, bulletin board system, web chat rooms, search engine, banners, uploadable file archives, and a form mail system are just a handful of examples of CGI programs.

A well written CGI program is easily transferable to other web servers. WebtoB is one such web server that a CGI program can easily run on.

While there are many ways to create CGI programs, the details will not be discussed in this document. This chapter describes how to configure the use of CGI in WebtoB.

CGI Configuration

In order to use CGI, the following sections must be configured.

This section describes how to use and configure SSI.

SSI Usage

SSI, short for Server Side Includes, can be used to create dynamic web pages. SSI can add Header files or add a function that can automatically adjust the last modified time of a document.

SSI can insert a 'command' in an HTML document. A server parses the SSI document for SSI commands and processes the commands. For example, a SSI command that modifies the last modification time is included in an HTML document; the server parses the command and modifies the last modified time.

Because HTML files that include SSI commands slow performance, SSI is disabled in WebtoB by default. To enable SSI, add a SSI server to the SERVER section in WebtoB environment file so that SSI is processed in another server.

The following is an example of the environment configuration to enable SSI.

*SVRGROUP
ssig         NodeName = mynode, SvrType = SSI

*SERVER
ssi          SvgName = ssig, MinProc = 10, MaxProc = 10

SSI Commands

All SSI commands in HTML documents are written as HTML comments.

SSI commands are generally wrapped in HTML comments "<!--... -->" as shown in the following. In the example, arg1 and arg2 are parameters and value1 and value2 are their respective values.

 <!--#command arg1="value1" arg2="value2" ... -->

The following is an example of flastmod, a command that outputs the modified time. 'file' is a parameter and "nextel.html" is the parameter value.

 <!--#flastmod file="nextel.html"-->

SSI command execution is variable name dependent. The following is an example.

 <!--#flastmod virtual="/" -->

The echo command retrieves the last modified time of the server web site. When the SSI command is executed, environment variables are set. These variables include CGI variables such as REMOTE_HOST, DOCUMENT_NAME, and LAST_MODIFIED.

<!--#echo var="LAST_MODIFIED" -->

This section describes how to use and configure PHP.

PHP Usage

PHP is a scripting language that is similar to Perl. PHP is popular due to its simplicity and performance advantages. PHP surpasses Perl in performance, development speed, and extendibility. Moreover, PHP is supported in Linux, UNIX, and Win32, which allows for web application development independent of the web server platform.

PHP can do everything that CGI can do such as retrieving form data, creating dynamic web pages, and managing web browser cookies.

PHP Configuration

In order to use PHP in WebtoB, installation is required. Using PHP is similar to using HTML or CGI, making it is easy to apply.

If a php3 module is required, additional configuration is necessary. Unlike php4 (.php), php3 uses the ".php3" extension. The use of php3 must be configured in the EXT section. The following is an example of the EXT section configuration.

*EXT
php3          Mimetype = "application/x-httpd-php3",
              SvrType = PHP

PHP Example

The following verifies PHP is installed and was configured successfully in WebtoB.

Virtual host is a feature available on web browsers that support HTTP 1.1. Virtual host allows a single web server to work as multiple web servers.

For example, a web newspaper service called “WebtoB Times” is created. This service can operate with a single IP, a domain name, and a single web server. However, multiple domain names can be beneficial so that services can be personalized without having to purchase additional IP addresses. Moreover, multiple domains will allow for easier management of services and future expansion.

The following domain names are offered to customers to specialize services.

Per the previous sample domain names, a virtual host feature can divide domain names to create HTML documents and to provide other services. To support the new domains, the web server can create an independent virtual host for each society and sports domain. The web server can also have separate document paths and configurations for each virtual host. Supporting multiple domains on a single IP address is called Name Based Virtual Host.

Alternatively, there is an IP Address Based Virtual Host that uses multiple domains and multiple IP addresses. However, this is less popular because it is difficult for a server to have multiple IP addresses.

The following is a Virtual Host structure. As shown, a single IP address and a single web server can service multiple domains. The virtual host of WebtoB can also separately process services referred by different names in the same IP.

The following is an example of the WebtoB virtual host configuration of the "WebtoB Times" example from the previous section. For efficient web operation, use VHOST section as follows.

*VHOST
society
    Docroot = "society_docs/",
    NodeName = webtob,
    Hostname = "society.webtobtimes.com",
    Port = "8080",
    IconDir = "society_icons/",
    LOGGING = "society_accesslog",
    ERRORLOG = "society_errorlog"

sports
    Docroot = "sports_docs/",
    NodeName = webtob,
    Hostname = "sports.webtobtimes.com",
    Port = "8080",
    IconDir = "sports_icons",
    LOGGING = "sports_accesslog",
    ERRORLOG = "sports_errorlog"

When deploying mass virtual hosts, configuring each virtual host is not necessary.

When using mass virtual hosts, the directory configuration pattern can be configured dynamically by using the following directives.

WebtoB stores all logs related to web service requests and services it provides into a log file specified in the environment file. The log file can be analyzed for various client and request data.

The log file, stored in the location specified in the environment file, can be stored anywhere in the machine. Improper log maintenance may cause performance and capacity issues for the server.

Log data is critical to system administrators. Web services can become more effective by mining user information. E.g., An online shopping mall administrator can obtain customer information to help increase sales. Because of the importance of logs, WebtoB administrators store log files to a specified location for management.

WebtoB creates three types of logs: an access log that is related to user requests; an error log that is related to error messages generated during processing requests; and a system log for the WebtoB system.

WebtoB can save access logs in multiple formats by configuring the Format item in the LOGGING section.

CLF (Common Logfile Format) is a standardized text format used by many administrators. Because the format is standardized and originated from NCSA, most web servers support this format. In WebtoB, CLF is the default log format.

The Common Logfile Format defined in W3C is as follows.

remotehost rfc931 authuser [date] "request" status bytes 

Define log parameters in the following order. Store the log in the location specified in the WebtoB environment file.

The following is an example of the log files stored in WebtoB.

143.248.148.42 - - [13/Feb/2001:16:46:13 +0900] "GET / HTTP/1.1" 304 -
143.248.148.42 - - [13/Feb/2001:16:46:14 +0900] "GET /index_pb.gif HTTP/1.1" 304 -
143.248.148.42 - - [13/Feb/2001:16:46:18 +0900] "GET /index.html HTTP/1.1" 200 7118
143.248.148.42 - - [13/Feb/2001:16:46:18 +0900] "GET /usage.png HTTP/1.1" 304 -
143.248.148.42 - - [13/Feb/2001:16:46:37 +0900] "GET /usage_200102.html HTTP/1.1" 404 148
143.248.148.42 - - [13/Feb/2001:16:47:21 +0900] "GET /index.html HTTP/1.1" 304 -
143.248.148.42 - - [13/Feb/2001:16:47:21 +0900] "GET /usage.png HTTP/1.1" 200 2509
143.248.148.42 - - [13/Feb/2001:16:47:24 +0900] "GET /usage_200102.html HTTP/1.1" 404 148
143.248.148.42 - - [13/Feb/2001:16:47:55 +0900] "GET /index.html HTTP/1.1" 304 -
143.248.148.42 - - [13/Feb/2001:16:47:55 +0900] "GET /usage.png HTTP/1.1" 304 -
143.248.148.42 - - [13/Feb/2001:16:47:57 +0900] "GET /usage_200102.html HTTP/1.1" 200 30798

In the example, a "-" in a field indicates missing data. The first column in the example displays the IP address of the connected client. In the following hyphens (-) represent the missing rfc931 and AuthUser data. In the square bracket [ ], user access time is displayed.

The information wrapped in double quotes is the request line from the client. The xnxt column is the HTTP status code of the response to the client. The last column is size of the object transmitted to the client from the server in bytes.

In WebtoB, the log format is configured in the Format item of the LOGGING section.

In order to record logs, configure the environment as follows:

*NODE
webmain
    WebtoBDir = "$WEBTOBDIR",
    SHMKEY = 69000,
    DOCROOT = "docs/",
    Port = "5469",
    Logging = "accesslog",
    ErrorLog = "errorlog"

*LOGGING
accesslog
    Format = "default",
    Filename = "log/access.log",
    Option = "Sync"
errorlog
    Format = "",
    Filename = "log/error.log",
    Option = "Sync"

The Logging item in the NODE section specifies the access log, while the ErrorLog item specifies the error log. In the LOGGING section of the configuration, the accesslog and errorlog sections define the log format, filename, and options of their respective logs.

The following directives can be used in format items to customize access logs.

"%h %l %u %t \"%r\" %s %b" corresponding to CLF, is set as the default value. In the previous example, the accesslog was set to default CLF format.

Including the %d option, several date and time types provided by the strftime function can be specified within {}. The default value is recorded in the same format as the %t directive: "[13/Feb/2001:16:47:24 +0900]".

The following format can be specified using directives.

custom_log1
    Format = "%h %l %u %t \"%r\" %s %b", 
    Filename = "log/custom1.log"
custom_log2
    Format = "[%{%Y.%m.%d %H:%M:%S}d] %a \"%r\" %s %T", 
    Filename = "log/custom2.log"

Because integration with Tmax uses WBAPI, creating an environment file is the same. The following example is an environment file.

<apsl.m>

*DOMAIN
webtob_apsl

*NODE
tmaxi2
    WebtoBDir="$WEBTOBDIR", 
    SHMKEY = 74125,
    Docroot = "docs/",
    Port = "8797", 
    HTH = 1,
    Logging = "log1",
    AppDir = "ap/",
    ErrorLog = "log2"

*SVRGROUP
htmlg    NodeName = "tmaxi2", SvrType = HTML
webapg  NodeName = "tmaxi2", SvrType = WEBSTD

*SERVER
wbsvrinit  SvgName = webapg, MinProc = 10, MaxProc = 10
wbquery    SvgName = webapg, MinProc = 10, MaxProc = 10 
wbsession  SvgName = webapg, MinProc = 10, MaxProc = 10 

*SERVICE
test       SvrName = wbsvrinit
query      SvrName = wbquery
wbsession  SvrName = wbsession

*URI
uri1      Uri = "/svct/", SvrType = WEBSTD

*LOGGING
log1
    Format = "default",
    Filename = "log/access.log",
    Option="Sync"
log2
    Format = "",
    Filename = "log/error.log",
    Option="Sync"

Refer to "Appendix C. Integration with Tmax" for more information on the apsl.m client program from the previous example.

In WebtoB and JEUS integration, JEUS connects to WebtoB. For best results, WebtoB should service the external network and JEUS the internal network. This is because internal network firewall is very strict with in-bound connections but tolerant with outbound connections.

When connecting JEUS to WebtoB, it is recommended to first start WebtoB and then JEUS. JEUS will attempt to connect to WebtoB during start up. If WebtoB is not online, JEUS will continually try to connect to WebtoB at regular intervals and output error messages to the JEUS log. Once the a successful connection has been made, a connection confirmation message is outputted to the JEUS log. With the successful connection, user requests, such as Servlet and JSP, are sent to JEUS through the connection.

The WebtoB and JEUS connection is persistent and does not disconnect unless a network error or a server failure occurs.

WebtoB Servlet Engine is sufficient for a business that requires simple online business services and logic. However, if a large-scale online service system is required, an integrated WebtoB and JEUS system is recommended.

WebtoB Environment File Configuration

JEUS 6 Environment File Configuration

The following path found in WEBMain.xml must be modified for the WebtoB connection configuration.

$JEUS_HOME/config/<node_name>/<node_name>_servlet_<engine_name>/

<WEBMain.xml>

<webtob-listener>
  <listener-id>webtob1</listener-id>
  <port>9999</port>
  <webtob-address>localhost</webtob-address>
  <registration-id>MyGroup</registration-id>
  <hth-count>1</hth-count>
  <thread-pool>
    <min>10</min>
    <max>10</max>
    <step>0</step>
    <max-idle-time>30000</max-idle-time>
  </thread-pool>
</webtob-listener>

In WEBMain.xml, the items under <webtob-listener>, which is under <webserver-connection>, must be modified. The following are descriptions for each item.

A context group can be connected to many web servers. Each web server must have a communication port. Being connected to many web servers is useful when multiple web servers are in different nodes or when receiving requests from multiple types of web servers.

Servlet Engine Starting Up And Shutting Down

WebtoB and WebtoB Servlet Engine can be started by using the steps listed in the following into a command console.

Example

Refer to "A.2. WebtoB and JEUS Integration Configuration" for more information.

The servlet engine provided by WebtoB Enterprise or above can be configured in the same way as when integrating JEUS. However, the aforementioned item names for JEUS 6 may be different from the current Servlet Engine version, which is for JEUS 7.

WebtoB Environment File Configuration

Configuration is identical to "WebtoB environment file configuration" in "4.5.2. JEUS 6 Integration Configuration (Standard+)".

Embedded Servlet Engine Environment File Configuration

For WebtoB connection configuration, domain.xml in the following path must be modified.

${WEBTOBDIR}/jeus/domains/domain1/config/domain.xml

<domain.xml>

<webtob-connector>
  <name>webtob</name>
  <network-address>
     <port>9999</port>
     <ip-address>localhost</ip-address>
  </network-address>
  <hth-count>1</hth-count>
  <thread-pool>
     <number>10</number>
  </thread-pool>
  <registration-id>MyGroup</registration-id>
  <output-buffer-size>8192</output-buffer-size>
  <reconnect-interval>5000</reconnect-interval>
</webtob-connector>

Items in the <webtob-connector> section must be modified in domain.xml. Descriptions for each item are as follows:

Starting and Terminating an Embedded Servlet Engine

In the commandline mode, start WebtoB and its embedded servlet engine in steps. For information about configuration, refer to the JEUS7 fix#4 manual.

Example

Refer to "A.2. WebtoB and JEUS Integration Configuration" for more information.

WebtoB uses the Reverse Proxy setting to connect to another web application server. The setting can also be used when WebtoB runs in an external network while the web application server runs in an internal network. In this setting, WebtoB can rewrite a response received from the internal server.

WebtoB attempts to connect to the target server when a client initiates an HTTP request. If the server is not running, it returns a 503 error to the client. If the connection is successful, WebtoB forwards the request to the server, receives a response from the server, and then sends it to the client.

WebtoB can reuse the connection by using the persistent connection setting, and this requires the PING check setting between the two servers. If the Min and Max settings are configured, connection is managed according to the number of concurrent requests and SSL communication can be used.

The WebtoB Enterprise edition provides the Reverse Proxy Group setting for a multi web application server configuration, and the Reverse Proxy setting can be used when connecting to a single server.

WebtoB Environment File Configuration

Checking the Configuration, Statistics, and Connection State

Use the wsadmin to check the configuration, statistics, and state of each connection.

In order to use the URLRewrite function, the URLRewrite item in the NODE section must be set to "Y". In the URLRewriteConfig item, configuration related to Condition and Rule must be set.

The following is an example of the NODE section configuration needed to use the URLRewrite function.

*NODE
mynode
    URLRewrite = Y,
    URLRewriteConfig = "${WEBTOBDIR}/config/rewrite.conf"

In URLRewriteConfig, RewriteCond and RewriteRule configurations can be used among the mod_rewrite functions of Apache. However, all configurations are not available, and some functions that will be later described are unavailable.

In order to configure RewriteCond, specify rewriting conditions as follows. Compare the TestString and Condpattern. If the conditions are met, RewriteCond is changed to the pattern defined in RewriteRule configuration.

RewriteCond <TestString> <CondPattern> [flags]

RewriteRule configures the rewriting of user requests. If a user request is matched to a RewriteCond, the matched pattern in the user request is replaced by a substitution specified in the RewriteRule configuration.

RewriteRule <Pattern> <Substitution> [flags]

The following are examples of URL Rewrite.