Configuring the IBM HTTP Server (powered by Apache) V9R0 for use with Output Manager

If you are configuring Output Manager as a plugin to the newer IBM® HTTP Server (powered by Apache) (IHSA) V9R0, follow these instructions.

Output Manager support for IHSA is limited to instances running in 64-bit mode only. It is recommended that ITOM be the only application running in a single instance of IHSA.

This installation uses two port numbers. The first port is for the main server task. The second port is used to configure the virtual host running the ITOMweb services. The second port number must be used in the URL that users specify in their browser to connect to the ITOMweb services.

To create a new instance of the IBM HTTP Server:

  1. Log in to the z/OS® UNIX System Services shell with the user ID that runs the installer.
  2. Navigate to the directory that ITOMweb was unpackaged into.
    For example:
    cd /u/bjt/httpx/om
  3. Copy omweb.vhost.conf.SAMPLE to omweb.vhost.conf. For example: 
    cp omweb.vhost.conf.SAMPLE  omweb.vhost.conf

    Take note of this location, you will need to reference it in a later step.

  4. Locate the IBM HTTP Server product code installation directory. For example: 
    cd /usr/lpp/ihsa_zos

    This example is the default. Ask your administrator for the location of the server product code directory.

  5. Set the umask value to 022 by specifying umask 022.
  6. Type the following command to run the installer program that will install the files into the installation directory, perform initial customization, and create symbolic links from the installation directory to the product directory: 
    bin/install_ihs -admin  server_installation_directory server_port
    where:
    • The -admin keyword is optional and allows you to use the administrative console to modify the httpd.conf file.
    • server_installation_directory is the installation directory for the server instance. This must not be the same as the product directory. The server_installation_directory will be created if it does not exist.
    • The non-SSL port for the web server is optional. The default port is 80. You can change the port on the Listen directive. Ask your administrator which port you should use. This is not the port number for the ITOMweb services.
    • Work with your network administrator to determine a port number to use for the ITOMweb server. This port number should not conflict with servers running on the same system.
    The following example invokes the command with support for modifying the APACHE httpd.conf file:
    /usr/lpp/ihsa_zos/bin/install_ihs -admin /etc/websrv1 80

    The following example invokes the command without support for modifying the APACHE httpd.conf file via the administration console: 

    bin/install_ihs /etc/websrv1 80
  7. After you have run the installation, change the ownership of the logs directory in the newly created directory tree: 
    cd server_installation_directory
chown <webserver user id> logs

    You may need superuser privileges to issue the chown command.

  8. Edit <apache_server_installation_directory>conf/httpd.conf
    Note: This is NOT the httpd.conf.SAMPLE included in the Output Manager pax file.
    1. Update @@ServerRoot@@ with the location specified for Server_installation_directory in step 6.
    2. Ensure that the Listen port (@@Port@@) is set to the ITOMweb server port number specified in step 6. For example: 
      Listen 28557
      Remember: Work with your network administrator to determine the port number to use for the ITOMweb server. This port number should not conflict with servers running on the same system.
    3. Update the @@ServerName@@ line with the DNS name where this server will be running.
    4. Update the ServerAdmin line. Change ServerAdmin you@your.address , by customizing it to ServerAdmin ITOM_Admin@yourcompany.com
    5. Find mod_authn_file.so and comment out the following line using a # sign at the beginning of the line:
      LoadModule authn_file_module modules/mod_authn_file.so
    6. Near line 835, in the section beginning with the "z/OS specific modules" comment, ensure that the following line is not commented out:
      LoadModule authnz_saf_module modules/mod_authnz_saf.so
LoadModule auth_basic_module modules/mod_auth_basic.so
LoadModule authz_core_module modules/mod_authz_core.so
    7. At the end of the file, add the ITOMWeb configuration file by adding the following lines, where itom mount point is the mount point that you specified when you ran BJT@JCPF:
      # Include ITOMWeb configuration 
Include /u/itom mount point/om/omweb.vhost.conf
      For example:
      # Include ITOMWeb configuration 
Include /u/web/httpd/om/omweb.vhost.conf
  9. Modify omweb.vhost.conf (created by the ITOMWeb installation). Replace all ?<xxx>? variables with suitable values for the IHSA server. The variables are:
    • ?/ITOMweb mount point?: Location where ITOMweb was installed.
    • ?HTTP_PORT?: Port number that this virtual host is listening on. Must be an available port, and cannot be the same as the port used for the main server.
      Note: This is the port number that users will specify when they connect to the ITOMweb services.
    • ?ADMIN_EMAIL?: Email address of server administrator
    • ?HOST_NAME?: Host name server is running on. The host name must be specified in UPPERCASE characters.
    • ?DB2SSID?: The Db2® subsystem name that contains Output Manager Db2 objects.
      Note: If the subsystem is in a data sharing group and you want Db2 to select which subsystem to use, enter the Group Attachment Name. If you want to specify the specific member of a data sharing group, or if the Db2 subsystem is not a member of a data sharing group, specify the Db2 Subsystem Name.
    • ?BJTPLAN?: Output Manager Plan name prefix
    • ?ITOMWEB_CONFIG?: Name of ITOMWeb configuration in Policy Administration. The default is "*".
    • ?ITOMWEB_LOG_FILE?: Pathname of file to write ITOMweb specific logging information to.
  10. Specify ITOMweb configuration parameters in the Output Manager ISPF interface:
    1. Navigate to the Policy Administration panel (ISPF A.PA).
    2. In the Subsystem field, enter the ITOMweb configuration value. This is the value that you specified in the ?ITOMWEB_CONFIG? variable above.
    3. In the Type field, type ITOMWeb.
    4. On the command line, type E and press Enter.

      If the E (edit) fails because the subsystem does not exist, use the I (initialize) command to create the subsystem. To do so, specify the name of the subsystem, type ITOMWeb for the subsystem type, and then enter an "I" command on the command line.

      The Policies panel is displayed.

      Note: The 'I' command is only used to store a new set of Subsystem/Type options when there are no variables in the database for that Subsystem/Type. The initialization sets each of the variables that is relevant to the specified type to the default values. The 'I' command cannot be used to reset existing variables in the Subsystem/Type to the default values.
    5. Specify ITOMweb configuration values:
      • ACCOUNTING_STRING: Specify a value for a Db2 accounting string. The default is none. If ACCOUNTINGSTRING is not specified, no value is provided to Db2. The ACCOUNTINGSTRING should not begin with the following three-character combinations: ARI, DSN, JCC, QSQ, or SQL. The maximum length is 255 characters If set to "USERID", USERID is replaced by the concatenation of BJT and the user ID of the requester.
      • ACCOUNTING_TOKEN: Specify a value for a Db2 accounting token. The default value is USERID, which uses the requester's user ID. The maximum length of this value is 22 characters.
      • AFP_CONV: This AFP support parameter enables the AFP conversion and viewing of reports in ITOMweb. Specify YES to enable AFP conversion.
        Note: You must also follow the directions in Adding Advanced Function Printing (AFP) support to ITOMweb.
      • AFP_CONVERSION_JOB_n: This AFP support parameter specifies AFP conversion JOB CARDS. If the JOB card needs more than 72 characters, specify this parameter multiple times. The AFP conversion job invokes the AFP proc specified by AFPPROCPDS and AFPPROCMEMBER.
        Note: If you used BJTCNVPM to convert the omweb.conf file from a previous release, you will need to manually edit the additional JOB card parameters that were stored in the ITOMWeb subsystem type. On the Policy Administration panel (ISPF A.PA), specify "*" in the Subsystem, and ITOMWeb in the Type field to edit the web server parameters. Then, on the Policies panel, add AFP_CONVERSION_JOB_n parameters to define up to 5 additional lines of JOB card options.
      • AFP_PROC_MEMBER: This AFP support parameter specifies the member name for the AFP conversion PROC (discussed in Adding Advanced Function Printing (AFP) support to ITOMweb). It is recommended to keep the original member name, BJT@AFP.
      • AFP_PROC_PDS: This AFP support parameter specifies the library name in which the customized BJT@AFP PROC is saved. This member is discussed in Adding Advanced Function Printing (AFP) support to ITOMweb.
      • Trace levels: Tracing can significantly increase the number of messages written to the HTTP Server SYSPRINT data set. When 0 (zero) is specified, tracing is disabled. Specify "1" to enable tracing. Tracing parameters include:
        • AUTH_TRACE_LEVEL
        • DB2_TRACE_LEVEL
        • JS_TRACE_LEVEL
        • PRINT_TRACE_LEVEL
        • WEB_TRACE_LEVEL
      • DEFAULT_ARCHIVE_CHARSET: This parameter is used to support foreign code page conversion to UTF-8. Specify the character set (charset) to assume for archive data sets if there is no other information in the archive data set or history DB that is more specific. USA English sites do not need this option, the default code set is sufficient. Set the argument to the code page for your local language environment.
      • DEFAULT_BANNER_PAGE: Designate a default banner page to be printed with all archive print requests unless overridden by the user. To override the default banner page, a user can assign a different banner page from the Print Settings window when printing an archive. The form of this parameter is: <pdsname>(<member>)
        Note: Reports are printed using the banner linked to the report definition.
      • DEFAULT_LINE_COUNT: Specifies the number of data LINES to return at one time, and the default number of lines displayed when a report is displayed in Line Mode.
      • DEFAULT_PAGE_COUNT: Specifies the number of data pages to return at one time. This parameter also designates the default number of pages displayed in Page Mode.
      • LOCALE: Specify your local language environment. This value follows the standard internationalization locale naming conventions. For example, US English is En_Us. This parameter is only required if your local language environment is not US English (En_US). The suffix should be .lp64
      • MAXIMUM_CONCURRENT_REQUESTS: (Optional) Specify the limit of the number of concurrent requests to be processed by ITOMweb services. When the number of requests sent to the HTTP server exceeds the specified value, additional requests will fail with 503 Server Busy error messages until the active workload drops below the limit. The default is no limit.
      • MAXIMUM_DOWNLOAD_LINES: Specify the maximum number of lines that can be downloaded at one time. Valid values are 0-2147483647. When 0 is specified, there is no limit to the number of lines that can be downloaded at one time.
      • MAXIMUM_DOWNLOAD_PAGES: Specify the maximum number of pages that can be downloaded at one time. Valid values are 0-2147483647. When 0 is specified, there is no limit to the number of pages that can be downloaded at one time.
      • MAXIMUM_INDEX_CHOICES: Specify the number of index values to send to the web client to present to the user. If there are more defined index values that meet the search criteria than the limit set in this parameter allows, a warning is posted next to the index and the user is prompted to narrow the search criteria and try again. The default is 100.
      • MAXIMUM_LINE_COUNT: Specify the maximum number of data lines that can be returned at one time. This parameter also controls the maximum number of lines displayed when a report is displayed in LineMode, the number of lines displayed when a one-page Archived Sysout is displayed in Page Mode, and the maximum number of lines displayed when a report is displayed as an html page (for archive data sets that do not have carriage control characters to start a new page).
      • MAXIMUM_LINE_IN_PAGE: Specify the maximum number of lines to display per page. This is relevant for archive data sets that do not have carriage control characters to start a new page. If the archive page length exceeds this value, a "more ..." link will appear indicating a partial display.
      • MAXIMUM_LISTING_LINES: Specifies the maximum number of rows to return for archive and report list queries.
      • MAXIMUM_PAGE_COUNT: Specifies the maximum number of data pages that can be returned at one time, and the maximum number of pages displayed in Page Mode.
      • Recall Processing: ITOMWeb submits a job to invoke the recall procs named in the following parameters.
        • RECALL_JOB_n
        • RECALL_MEMBER
        • RECALL_PDS
      • REPORT_ACCESS_ID: Specifies the userid used to access the underlying data set to read a report. Specify the userid of the ITOMweb server.
      • REPORT_CLICK: Include this parameter to open reports and archives in a new tab or window when a user clicks a report or archive in a list of results. Your current browser settings determine whether a new tab or window is used. Excluding this command (default), opens the archive or report in the current tab or window, replacing the archive or report list. Use REPORTCLICK to avoid having to re-issue queries to search for archives or reports.
      • REPORT_DEF_FILE: Specify the pathname of the administrative report definition file. The administrative report definition file is typically named adminreports.enc in the WEBROOT directory.
      • SCROLL_BY_PAGE: Determines how the previous ( < ) and next ( > ) buttons operate. Specify YES (default) to scroll by page, one page at a time. Specify NO to scroll by the values specified in the DEFAULTPAGECOUNT / DEFAULTLINECOUNT parameters.
      • SEARCH_FIRST: Specify YES or NO to determine whether or not a search panel is displayed automatically before a query is issued when a user clicks the Reports or Archives buttons on the ITOMweb home page. The default is NO, which will return a list of archives or reports from the last 7 days.
      • SEARCH_LAST_N_DAYS: Include this parameter to enforce a date range for all ITOMweb searches (unless explicitly overridden), and specify the initial value for LAST N Days. Excluding this parameter allows the search panel to open with no constraints on date range.
      • SHOW_ARCHIVES: This is an ITOMweb navigation option. Specify TRUE to enable the Archives link on the ITOMweb home page. If FALSE is specified, an "Archive Viewing Not Enabled" error message is displayed when a user clicks the Archives link.
      • SHOW_INDICES: This is an ITOMweb navigation option. Specify TRUE to allow access to indexed reports. Users can access indexed reports by clicking the Reports link and then selecting a report with type "I". If FALSE is specified, an "Index Viewing Not Enabled" error message is displayed when a user clicks an indexed report.
      • SHOW_INDICES_IN_HOMEPAGE: This is an ITOMweb navigation option. Specify TRUE to display an Indexed Reports link on the ITOMweb home page. If FALSE is specified, this link is not displayed but users can still access indexed reports by clicking the Reports link and then selecting a report with type "I" (if SHOWINDICES is also set to TRUE). The default is FALSE.
      • SHOW_REPORTS: This is an ITOMweb navigation option. Specifying TRUE will enable the Reports link on the ITOMweb home page. If FALSE is specified, a "Report Viewing Not Enabled" error message is displayed when a user clicks the Reports link.
      • USE_FORMATTED_VIEWS: Specifies whether or not formatted views are used. Although all users can see and use all views and filters, the privilege of editing or deleting views and filters is controlled by the BJT.?BJTQUAL?.ADM.FVF security profile. Administrators must have ALTER access. Users with UPDATE access can create new views and edit them later. Other users can only edit and delete the views and filters that they have created. When a view or filter is created, the creator's user ID is associated with the new filter or view, and all other users (except administrators) will be prevented from editing or deleting it. Additionally, a filter that is linked to a view cannot be deleted.
      • WEB_ROOT: Specify the root USS directory for ITOMweb; the webroot directory.
      • WELCOME_TEXT: Include this parameter to specify the "Welcome message" text that appears at the top of the home page. For example, WELCOMETEXT=Welcome to Output Manager
  11. To assign an owner to the started task, the stc-owner-userid must have the following RACF® requirements:
    • stc-owner-userid must be RACF defined with NOPASSWORD
    • must have an OMVS segment with a unique UID
    • HOME must be a valid directory (for example: ?/ITOMweb mount point?)
    • PERMIT stc-proc-name.* CLASS(FACILITY) STDATA(USER(stc-owner-userid), GROUP(stc-owner-group)) SETROPTS RACLIST(STARTED) REFRESH
  12. If you are using Db2 Resource Recovery Services attachment facility, you also need the following additional RACF definition: 
    PERMIT ?DB2SSID?.RRSAF CLASS(DSNR) ACCESS(READ) 
ID(stc-owner-userid) SETROPTS RACLIST(DSNR) REFRESH
  13. You can start the IBM HTTP Server instance from the MVS™ console by creating a JCL cataloged procedure for the instance.
    For example in the started task start procedure HTTPSV9: 
    //*---------------------------------------------------------            
//IHSAPACH PROC ACTION='start',                                       
//  DIR='//u/websrv/bjt/IHSA/V9.0',                                    
//  CONF='conf/httpd.conf'                                              
//*---------------------------------------------------------            
//IHS EXEC PGM=BPXBATCH,                                                
//  PARM='SH &DIR/bin/apachectl -k &ACTION -f &CONF -DNO_DETACH',       
//  MEMLIMIT=512M                                                       
//STEPLIB DD DSN=DB2A.SDSNEXIT,DISP=SHR
//             DD DSN=DSN.VA10.SDSNLOAD
//OUTDSC   OUTPUT DEST=HOLD      
//SYSPRINT DD SYSOUT=A,OUTPUT=(*.OUTDSC)                                
//STDOUT DD PATH='&DIR/logs/proc.output',                               
//  PATHOPTS=(OWRONLY,OCREAT,OTRUNC),                                  
//  PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIWGRP)                              
//STDERR DD PATH='&DIR/logs/proc.errors',                               
//  PATHOPTS=(OWRONLY,OCREAT,OTRUNC),                                   
//  PATHMODE=(SIRUSR,SIWUSR,SIRGRP,SIWGRP)                              
//    PEND
    To start the server, enter "S HTTPSV9" on the system console.
    Note: You can change the value of ACTION from "start" to "restart". This functions like ‘start’ if the web server is not up and running and will quickly restart it if it is up and running.

    To stop the server, enter "P HTTPSV9" on the system console.

  14. Connect to the ITOMWeb server at the following URL: http://@@ServerName@@:<APACHE_PORT>/OM
    Note: <APACHE_PORT> is the port number specified in the omweb.vhost.conf file and it is different from port number specified in httpd.conf file