A tc Runtime service represents the combination of one or more connector components that share a single engine component for processing incoming requests. You can create or configure the tc Runtime services.

A tc Runtime service represents the combination of one or more connector components that share a single engine component for processing incoming requests. A tc Runtime consists of one or more services. The default tc Runtime service which is always present in the newly created tc Runtime instance is called catalina.

You create and configure tc Runtime services in the Views > Server Configuration > Servicestab.

Table 1. General Properties

Field Name

Description

Name

Specifies the name of the tc Runtime service. The service name must be unique within the scope of a tc Runtime instance. The name that you specify appears in the tc Runtime log messages.

Connector Properties

Each tc Runtime service can have one or more connectors configured. Connectors are specific to a protocol, such as HTTP or AJP.

Table 2. General Properties

Field Name

Description

Protocol

Specifies the protocol that handles incoming and outgoing messages for the connector. The following values are valid:

  • org.apache.coyote.http11.Http11Protocol (same as HTTP/1.1). This is the default value. If you want to use HTTPS, do not specify HTTPS/1.1. Set the secure field to true.

  • org.apache.coyote.http11.Http11NioProtocol - non blocking Java connector

  • org.apache.coyote.http11.Http11AprProtocol - the APR connector.

IP Address

For tc Runtime instances with more than one IP address, this attribute identifies a single address, on which the listen port defined in the Port attribute is opened for connections. If a specific IP address is not specified, server sockets are created on all IP addresses associated with the server, on the port specified in the Port attribute.

Port

Specifies the TCP port number on which the connector creates a server socket and waits for incoming connections. The operating system allows only one server application to listen on a specific port number on a specific IP address, which means that multiple tc Runtime instances running on the same computer must have unique port numbers. Default value is 8080.

Accept Count

HTTP(S) Connectors only. Specifies maximum queue length for incoming connection requests when all possible request processing threads are in use. Any requests received when the queue is full are refused. The default value is 10.

Max Keep Alive Requests

HTTP(S) Connectors only. Specifies the maximum number of HTTP requests that can be pipelined until the connection is closed by the server. A value of 1 disables HTTP/1.0 keep-alive, as well as HTTP/1.1 keep-alive and pipelining. A value of -1 allows an unlimited number of pipelined or keep-alive HTTP requests. The default value is 100.

Proxy Host

If the connector is being used in a proxy configuration, specifies the server name that is returned from calls to request.getServerName().

Proxy Port

If the connector is being used in a proxy configuration, specifies the server port that is returned from calls to request.getServerPort().

Redirect Port

Specifies the port to which a user is redirected if they require a secure connection. If the connector supports non-SSL requests, and a request is received for which a matching requires SSL transport, tc Runtime automatically redirects the request to the port number specified here.

Scheme

Specifies the name of the protocol to have returned by calls to request.getScheme(). For example, set this field to https for an SSL Connector. The default value is http.

Connection Timeout

Specifies the number of milliseconds the connector waits, after accepting a connection, for the request URI line to be presented. The default value is 60000 (i.e. 60 seconds).

Max Threads

Specifies the maximum number of request processing threads that the connector creates, which in turn determines the maximum number of simultaneous requests that can be handled. If an executor is associated with the connector, tc Runtime ignores this attribute as the connector will execute tasks using the executor rather than an internal thread pool. The default value of this field is 40.

Request Secret Password

Specifies that only requests from workers with the secret keyword will be accepted.

Use Request Secret Keyword

Specifies whether tc Runtime should generate a random value for the Request Secret Keyword field.

Table 3. Security/SSL Properties

Field Name

Description

Secure

Specifies whether you want user calls to request.isSecure() to return true for requests received by the connector. Select this field for connectors (both SSL and non-SSL) that receive data from an SSL accelerator, such as a crypto card, an SSL appliance or a Web server.

Enable SSL

Enables SSL traffic (handshake/encryption/decryption) for the connector. When enabled, ensure that you also set the scheme and secure attributes so that correct values are returned to user calls to request.getScheme() and request.isSecure().

Certificate Encoding Algorithm

Specifies the certificate encoding algorithm. The default value is the Sun implementation (SunX509). For IBM JVMs, use the value IbmX509. For other vendors, consult the JVM documentation for the correct value.

Keystore File

Specifies the path name of the keystore file that contains the server certificate to be loaded. By default, the path name is the file *.keystore in the operating system home directory of the user that starts the tc Runtime instance.

Keystore Password

Specifies the password used to access the server certificate from the specified keystore file. The default value is changeit.

Key Alias

Specifies the alias that tc Runtime uses when accessing the server certificate in the keystore. If not specified, tc Runtime uses the first key read in the keystore.

Engine Properties

A tc Runtime engine represents the entire request processing structure associated with a particular service. It receives and processes all requests from one or more connectors, and returns the completed response to the connector for ultimate transmission back to the client.

Each Service must be associated with only one engine.

Table 4. Engine Properties

Field Name

Description

Name

Specifies the name of the service. This is the name used in tc Runtime logging messages. Each service name must be unique within the scope of a tc Runtime instance.

Default Host

Specifies the default host name. The name corresponds to the name of a Host component that processes requests directed to host names on the server, but which are not explicitly configured for the tc Runtime instance.

JVM Route

Specifies the identifier that must be used in load balancing scenarios to enable session affinity. The identifier, which must be unique across all tc Runtime instances that comprise the cluster, is appended to the generated session identifier, allowing the front end proxy to always forward a particular session to the same tc Runtime instance.

Thread Diagnostics

When you deploy and start a Web application on a tc Runtime instance, and clients begin connecting and using the application, you might find that the clients occasionally run into problems such as slow or failed requests. Although by default tc Runtime logs these errors in the log files, it is often difficult to pinpoint exactly where the error originated, and how to fix it. By enabling thread diagnostics, tc Runtime provides additional information to help troubleshoot the problem.

A failed request is one that did not execute. A slow request is a request that takes longer to process than the configured threshold. The default threshold is 500 milliseconds.

When you enable thread diagnostics, you can view the following contextual information about a slow or failed client request:

  • The time and date when the slow or failed request occurred.

  • The exact URL invoked by the client that resulted in a slow or failed request.

  • The exact error returned by the request.

  • The database queries that were executed as part of the request and how long each one took.

  • Whether any database connection failed or succeeded.

  • Whether the database had any other connectivity problems.

  • Whether the database connection pool ran out of connections.

  • Whether any garbage collection occurred during the request, and if so, how long it took.

Table 5. Thread Diagnostics Properties

Field Name

Description

Enable Thread Diagnostics

Enables the gathering of thread diagnostic information.

To view the information after you have enabled thread diagnostics, go to the Monitor tab of a specific tc Runtime instance, then click the servername Thread Diagnostics link in the Resources > Services window on the left.

History

Specifies the maximum number of requests that have met the threshold condition that tc Runtime keeps as historical data. The default value is 1000. You can query this historical data using JMX. It is not shown in the vRealize Hyperic user interface.

Threshold

Specifies the threshold, in milliseconds, after which a client request is considered slow. The default value is 5000 milliseconds.

Host Properties

A tc Runtime host represents a virtual host, which is an association of a network name for a tc Runtime, for example www.mycompany.com, associated with the specific tc Runtime . To be effective, the network name must be registered in the Domain Name Service (DNS) server that manages the Internet domain to which you belong.

A tc Runtime engine must be associated with one or more hosts. One of the hosts must be the default host, or the one pointed to by the Default Host field of the engine configuration.

Table 6. Host Properties

Field Name

Description

Name

Specifies the network name of the virtual host, as registered in your Domain Name Service (DNS) server. One of the Hosts associated within a tc Runtime engine must have a name that matches the Default Host setting for that engine.

Application Base Directory

Specifies the application base directory for the virtual host. The application base directory may contain Web applications to be deployed on the virtual host. You can specify an absolute pathname for this directory, or a pathname that is relative to the $CATALINA_BASE directory.

Auto Deploy Web Applications

Specifies whether new Web applications that are copied to the application base directory while tc Runtime is running should be automatically deployed.

Deploy Applications on Startup

Specifies whether Web applications from this host should be automatically deployed when the tc Runtime instance starts up.

Unpack WARs

Specifies whether tc Runtime should unpack Web applications that are copied to the application base directory as WAR files into a corresponding disk directory structure. If unselected, tc Runtime runs the Web applications directory from a WAR file.

Deploy XML

Specifies whether tc Runtime should parse the context.xml file embedded inside the Web application (located at /META-INF/context.xml). Security conscious environments should set this to false (unselected) to prevent applications from interacting with the container's configuration. The administrator is then responsible for providing an external context configuration file, and putting it in $CATALINA_BASE/conf/enginename/hostname/.

Work Directory

Specifies the pathname to a scratch directory used by applications for the host. Each application has its own sub directory with temporary read-write use. A context work directory overrides use of the host work directory configuration. This directory is made visible to servlets in the Web application by a servlet java.io.File types context attribute named javax.servlet.context.tempdir, as described in the Servlet specification. If not specified, a suitable directory underneath $CATALINA_BASE/work is provided.

HTTP Access Logging

The tc Runtime logging subsystem creates log files in the same format as those created by standard Web servers. These logs can later be analyzed by standard log analysis tools to track page hit counts, user session activity, and so on. The log files are rolled over daily at midnight.

Table 7. HTTP Access Logging Properties

Field Name

Description

Enable Logging

Specifies whether logging is enabled on the engine or virtual host.

Directory

Specifies the absolute or relative pathname of a directory in which tc Runtime creates the log files. If you specify a relative pathname, it is relative to $CATALINA_BASE. The default value is $CATALINA_BASE/logs.

Pattern

A formatting layout that identifies the various information fields from the request and response to be logged, or common or combined to select a standard format. Optimized access only supports common and combined as the value for this attribute.

File Name Prefix

Specifies the prefix added to the start of each log file's name. The default value is access_log. Leave the field blank if you do not want a prefix.

File Name Suffix

Specifies the suffix added to the end of each log file's name. Leave the field blank if you do not want a suffix (default behavior).

File Date Format

Specifies a customized date format in the access log file name. The date format also specifies how often the file is rotated. For example, if you want the log files to rotate every hour, set the value to: yyyy-MM-dd.HH