Configuring Tomcat for BMC AMI Ops Console Management

BMC AMI Ops Console Management provides you with a customized version of the Apache Tomcat (Tomcat) web server for the best possible out-of-the-box experience. BMC AMI Ops Console Management requires Tomcat for configurational purposes. Tomcat is also required to configure an application server for the operator viewers.

Related topics

Using

Overview

The customized Tomcat server provides the following features:

  • Removal of nonessential services
  • HTTPS certificate usage and encryption
  • Administrator authentication and authorization

This topic provides information about using the Tomcat web server with BMC AMI Ops Console Management.

For more information about Tomcat, see the Tomcat website.

Obtaining Tomcat

BMC AMI Ops Console Management is delivered with Apache Tomcat pre-configured for use. If you want, you may replace the delivered version of Apache Tomcat with your own. 

You can obtain the latest version of the tar.gz Tomcat file from the 10.1.x branch on the Tomcat website. This version is the most efficient and it is still supported. This topic focuses on customizing this version of Tomcat. The tar.gz download file maintains the Linux permissions on scripts and other files.

Tomcat subdirectories overview

After you download and unpack the Tomcat file, you can view the following subdirectories.

Important

All subdirectory names are in lower case.


Subdirectory

Data in the subdirectory

bin

Contains scripts for running, starting, and stopping Tomcat.

conf

Contains configuration files.

The most important configuration file, server.xml  is present in this subdirectory, which performs most of the customization.

lib

Contains Tomcat JAR files.

These JAR files are the executable libraries used by the server itself.

logs

Contains log files.

Initially, this is an empty directory. Once you start using Tomcat, the subdirectory starts to store log files.

temp

Contains Tomcat temporary files.

For example, when you upload a file, it is saved here.

webapps

Contains Tomcat webapp file, which is a .war file (like a zip or jar file).

.war files contain web pages and other codes to display and process web pages.

work

Contains web applications and Java Server Pages (JSPs).

The JSPs contain a combination of HTML text and Java code. Tomcat generates executable code and saves it in the work directory.

Removing unused components

Out-of-the-box Tomcat contains several web applications, which enable an administrator to get Tomcat up and running quickly.

These web applications are not necessary for BMC AMI Ops Console Management. We recommend you delete the following directories:

  • webapps/docs
  • webapps/examples
  • webapps/host-manager
  • webapps/manager
  • webapps/ROOT


Important

When BMC AMI Ops Console Management is installed, it provides its own ROOT.war file, which expands into the ROOT subdirectory. After BMC AMI Ops Console Management is installed, do not delete this directory.

Customizing Tomcat for BMC AMI Ops Console Management

You need to customize Tomcat to make it work efficiently with BMC AMI Ops Console Management.

Most web pages and servlets that BMC AMI Ops Console Management uses are secured. Some web pages and servlets are secured by using encryption alone, while some are secured by encryption along with authentication and authorization.

You can use Tomcat Connectors to configure an encryption method. You can use Tomcat Realms to configure authentication and authorization. These elements are defined in the conf/server.xml file.

Tomcat Connectors

A Tomcat Connector is an internal component that creates a server socket that listens for network connections. You can customize many different aspects of a connector.

Important

BMC AMI Ops Console Management requires a secure Connector (HTTPS) to operate.

For more information about Tomcat Connectors, see Apache Tomcat 10.1.x Configuration Reference on the Tomcat website. Tomcat Connectors are configured in the conf/server.xml file.

Tomcat is configured on startup to listen on TCP/IP port 8080 in clear text (that is, not encrypted). Although no encryption is provided, a few examples appear in the comments.

To create SSL-enabled Connectors, see SSL/TLS Configuration How-To on the Tomcat website.

Tomcat client certificate configuration

Tomcat may be configured to require client certificates for authentication. To enable client certificate checking:

  1. Import the signer certificate from your certificate authority into the trust store. Use the mvcm_trust_add.sh script.

  2. Update the SSLHostConfig element in the Tomcat server.xml file. Set the certificateVerification attribute to Required.
    For all the additional available configuration options, see the SSL Support - SSLHostConfig attributes on the Tomcat website. 

  3. Configure your authentication properties as required.
  4. Restart Tomcat.

When a user accesses the web page, the web browser looks up the appropriate user certificate and sends it to the server. Tomcat then validates the user’s certificate against what is in the trust store. After the browser sends the user’s certificate and the web server accepts the certificate, the user’s certificate is passed to the authentication server. The authentication server verifies that the user is authorized to access BMC AMI Ops Console Management through the existing mechanisms.

If the authentication method is set to Database, the user must be entered into the database. The roles assigned to the user are then retrieved.

If the authentication method is set to LDAP, a connection is made to the LDAP server and a search is done according to the search filter.

Important

The LDAP configuration is different here. You cannot use the connect DN and connect password based on the user's credentials since the user’s password is not sent. You must use a system account and then use the search filter as shown in the example below:

Example:

Server URI

ldaps://ldap.example.com

Connect DN

CN=system,OU=System accounts,DC=myorg,DC=example,DC=com

Connect password

superSecretPassword

Base DN

DC=myorg,DC=example,DC=com

Search Filter

&((sAMAccountName={0})(memberOf=CN=Mainframe Operators, DC=myorg,DC=example,DC=com))

This verifies that the user has an account in your LDAP server and is a member of the appropriate group. The {0} token is the common name (CN) from the certificate.

If you want to allow all users with a valid certificate, you should have a simple authentication program that exits with a 0 status. For example:

#!/bin/sh
exit 0

In all cases, the database is checked to assign the Product Administrator, User Administrator, and Product Operator roles.

Deploying BMC AMI Ops Console Management webapps

BMC AMI Ops Console Management installers automatically deploy all the required webapps. You must deploy the webapps manually when you use your own Tomcat installation by copying all the files from /usr/iocinst/apps/webapps to /usr/tomcat/webapps. Tomcat automatically monitors its webapps directory and deploys new webapps as required.

Important

  • Automatic deployment might be disabled, so you might need to restart Tomcat.
  • In Tomcat, the ROOT.war file conflicts with the ROOT webapp by default.

Controlling Tomcat as a daemon

You can use the systemd daemon manager to control Tomcat as a daemon.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*