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.
Avoid trouble: The web server that is provided with
IBM® i, is already installed
under product 5761-DG1 for
IBM i V6R1 or 5770-DG1 for
IBM i V7R1. The
IBM i web server is referred
to as the IBM HTTP Server for
IBM i. This web server
is different from the IBM HTTP
Server that is provided with
WebSphere Application Server, which does not
run on
IBM i.
gotcha
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.
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
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 web Server Plug-ins Configuration Tool to install the appropriate
plug-in file to your web server. Then, run the configureweb_server_name script created by the tool 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 plug-in for IBM HTTP Server for WebSphere Application Server on z/OS.
If you are using
the IBM HTTP Server Version 5.3, which is provided with the z/OS base operating system, see
the information about installing and configuring the web server plug-in
for IBM 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 and 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.
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
About this task
The appropriate plug-in file is installed.
In addition, an http profile is created (/QIBM/UserData/WebSphere/Plugins/V85/webserver/profiles/http). The http profile can be used to facilitate
the creation of web server definitions. See the topic about selecting
a web server topology diagram and road map for instructions on how
to configure IBM HTTP Server
for IBM i to communicate with
an application server.
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
![[z/OS]](../images/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.
- 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.
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
When you configure 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.
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
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 web server are on different workstations.
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.
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:
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
- 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.
Propagate the plug-in configuration. To propagate the plug-in configuration from the administrative
console, click web_server_name. Another method to propagate the plug-in configuration is to
run the GenPluginCfg command. For more information,
see the GenPluginCfg command documentation.
You do not need to propagate the plug-in configuration if the
web server is on the same machine as the associated stand-alone version
of the product. If the propagation of the plug-in configuration fails
due to an unknown cause, you must manually copy the plugin-cfg.xml file to the location for the remote web server installation.
Avoid trouble: If you use the FTP function
to perform the copy, and the configuration reload fails, check the
file authorities on the
plugin-cfg.xml file and
make sure that users QTMHHTTP, QNOTES and QEJBSVR have RWX authority.
If the authorities are not correct, the web server cannot access the
new version of the file, which causes the configuration reload to
fail. To check the authorities, run the following IBM i command:
wrklnk 'plug_in_folder_location/plugin-cfg.xml'
Then select option 9 to view the authorities that are assigned to
the users (QTMHHTTP, QNOTES, and QEJBSVR).
gotcha
If the authorities
are incorrect, issue the following IBM i command to change the file authorities to the appropriate
settings: CHGAUT USER(QEJBSVR QTMHHTTP QNOTES) OBJ('plug_in_folder_location/plugin-cfg.xml') DTAAUT(*RWX)
The plug_in_folder_location is the location you specified
when you transferred the plugin-cfg.xml file.
- You might have to stop the application server and then
start the application server for the web server to locate the plugin-cfg.xml file.
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
Tune your web server. See the page about tuning web servers for more information.
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
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 that has a running IBM HTTP Server administration server.
If neither of these conditions are true, you must manually
copy the plugin-cfg.xml file to the location
of the remote web server installation. Copy the plugin-cfg.xml file in <app_server_root>/profiles/<profilename>/config/cells/../../nodes/../servers/<webservername> to the web server host location,
which is <PluginInstallRoot>/config/<webservername>/.
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 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.