This topic describes how to implement a web
server plug-in. The product works with a web server to route requests
for dynamic content, such as servlets, from web applications. The
web servers are necessary for directing traffic from browsers to the
applications that run on an application server. The web server plug-in
uses the XML configuration file to determine whether a request is
for an application server.
Before you begin
- See the information about choosing a front end for your WebSphere® Application Server topology. This
topic helps you determine whether to set up a web server plug-in,
a proxy server, or a secure proxy server to provide session affinity,
failover support, and workload balancing for your WebSphere Application Server topology.
- Install your web server if it is not already installed.
If you want to use the IBM® HTTP Server that is provided with the product,
see the information about installing IBM HTTP
Server. Otherwise, see the installation information that is provided
with your web server.
Make sure the appropriate plug-in file has
been installed on your web server and the configureWeb_server_name script
has been run to create and configure the web server definition for
this web server.
If you are using a distributed
platform web server, use the Plug-in Installation wizard to install
the appropriate plug-in file to your web server. Then run the configureWeb_server_name script
created by the wizard to create and configure the web server definition
in the WebSphere configuration
repository.
If you are using the IBM HTTP Server for z/OS® powered by Apache, which is provided with
the product, see the information about installing and configuring
the web server plug-in for IBM HTTP
Server for WebSphere Application Server on z/OS.
If you
are using the HTTP Server Version 5.3, which is provided with the z/OS base operating system, see
the information about installing and configuring the plug-in for HTTP
Server for z/OS V5.3.
If you are using a distributed platform web server
with a version of the product that is running on z/OS operating systems, use an FTP connection
to send the plug-in to the web server. Use the Plug-in Installation
Wizard to install the appropriate plug-in file to your web server.
- If you are making a series of simultaneous changes, such as installing
numerous applications, you might want the configuration service disabled
until after you make the last change. The web server plug-in configuration
service is enabled by default. To disable this service, in the administrative
console click server_name, and then clear the option.
About this task
![[z/OS]](../../ngzos.gif)
The following steps are performed during the plug-in
installation process. See the Plug-in Installation Roadmap for additional
information.
A
node is created. An unmanaged node is created
when the web server is on a different computer from the application
server. An unmanaged node is a node that does not have a node agent
running on it. Using unmanaged nodes, the product can represent servers
that are not application servers within its configuration topology.
This representation enables connection information between those servers
and application servers to be maintained. See the topic about adding,
managing, and removing nodes for more information.
- A web server definition is created.
You can also use either
the administrative console or use the ConfigureWebServerDefinition.jacl
script to create a web server definition. If you use the administrative
console:
- Select the node that was created in the preceding step, and in
the server name field, enter the local name of the web server for
which you are creating a web server definition.
- Use the wizard to complete the web server definition.
- An application or modules are mapped to a web server. If an application
that you want to use with this web server is already installed, the
application is automatically mapped to the web server. If the application
is not installed, select this web server during the "Map modules to
servers" step of the application installation process.
- The master repository is updated and saved.
When you install a plug-in, the configuration
file for that plug-in is automatically created. You can change or
tune the default settings for the properties in this configuration
file. If you change any of the settings, you must regenerate the file
before your changes take effect.
Generating
or regenerating the configuration file might take a while to complete.
After it finishes, all objects in the administrative cell use their
newest settings, which the web server can access. If the application
server is on the same physical workstation as the web server, the
regeneration usually takes about 30 to 60 seconds to complete. The
regeneration takes longer if the application server and the web server
are on different workstations.
Avoid trouble: If
your installation uses a firewall, make sure that you configure the
web server plug-in to use a port that has been opened. See your security
administrator for information about how to obtain an open port.
gotcha
The
following procedure describes the steps for updating the plug-in configuration
file, including configuring for SSL and web server tuning.
Procedure
- Use the administrative console to change the settings in
the plug-in configuration file.
When setting up your
web server plug-in, you must decide whether to have the configuration
automatically generated in response to a configuration change. When
the web server plug-in configuration service is enabled and any of
the following conditions occur, the plug-in configuration file is
automatically generated:
- When the web server is created or saved
- When an application is installed
- When an application is uninstalled
- When the virtual host definition is updated
Avoid trouble: When the plug-in configuration file is first generated,
it does not include admin_host on the list of virtual hosts. The information
about allowing web servers to access the administrative console describes
how to add it to the list.
gotcha
You can either use the
administrative console, or issue the
GenPluginCfg command
to regenerate your
plugin-cfg.xml file.
Avoid trouble: You must delete the
plugin-cfg.xml file
in the
profile_root/config/cells directory
before you complete this task. Otherwise, configuration changes do
not persist to the
plugin-cfg.xml file.
gotcha
Complete
the following steps to regenerate your plugin-cfg.xml file
by using the administrative console:
- Select web_server_name.
- Select Automatically generate plug-in configuration
file, or click one or more of the following topics to manually
configure the plugin-cfg.xml file:
- Caching
- Request and response
- Request routing
- Custom Properties
See the topic about web server plug-in configuration properties
for information about how to map each property to one of these topics.
Avoid trouble: Do not manually update the
plugin-cfg.xml file.
Any manual updates you make for a web server are overridden whenever
the
plugin-cfg.xml file for that web server is
regenerated.
gotcha
- Click OK.
- You might need to stop the application server, and then
restart the application server for the web server to locate the plugin-cfg.xml file.
Tune your web server. See the page about tuning web servers for more information.
Propagate the plug-in configuration.
The plug-in configuration file, plugin-cfg.xml,
is automatically propagated to the web server if the web server plug-in
configuration service is enabled, and one of the following conditions
is true:
- The web server is a local web server, which means that the web
server is located on the same workstation as an application server.
- The web server is a remote IBM HTTP
Server Version 7.0 that has
a running IBM HTTP Server administration
server.
If neither of these conditions is true, you must manually
copy the plugin-cfg.xml file to the location
of the installation for the remote web server. Copy the plugin-cfg.xml file
in app_server_root/profiles/<profile_name>/config/cells/../../nodes/../servers/web_server_name to
the web server host location, which is <Plugin_Install_Root>/config/web_server_name/.
Important: If you use the FTP function to copy the file, and
the configuration reload fails, check the file permissions on the
plugin-cfg.xml file,
and make sure that they are set to
rw-r--r--. If
the file permissions are not correct, the web server is not able to
access the new version of the file, which causes the configuration
reload to fail.
If the file permissions are incorrect, issue the
following command to change the file permissions to the appropriate
settings:
chmod 644 plugin-cfg.xml
The AIX® FTP function does not preserve
file attributes. Therefore, if you need to manually copy the plugin-cfg.xml file
from an AIX operating system,
you might want to use the AIX RCP
function instead of the FTP function to copy the file.
The remote web server
installation location is the location you specified when you created
the node for this web server.
- Copy the keystore file to the keystore directory
on your web server.
Avoid trouble: This step
is required for the web server to function properly.
gotcha
For
detailed instructions on copying the keystore file, read the topic
on configuring the web server plug-in for Secure Sockets Layer.
Results
The configuration is complete. To activate the configuration,
stop and restart the web server. If you encounter problems restarting
your web server, check the
http_plugin.log file
for information about what portion of the
plugin-cfg.xml file
contains an error. The log file states the line number on which the
error occurred, along with other details that might help you diagnose
why the web server did not start. You can then use the administrative
console to update the
plugin-cfg.xml file.
If
applications are infrequently installed or uninstalled, which is usually
the situation in a production environment, or if you can tolerate
the performance impact of generating and distributing the plug-in
configuration file each time any of the previously listed actions
occur, consider enabling the configuration service.