Skip to end of metadata
Go to start of metadata

The features described on this page are available in tc Server and tc Server Standard Edition.

Feedback is welcome. Click Add Comment at the bottom of the page.

tc Runtime Services Reference

This page defines the fields on the Views > Server Configuration > Services tab used to configure and create 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 newly created tc Runtime instance is called "catalina."

See The Service Component on the Apache Web site for more information.

General Service Properties

Field Name
 Description
Name Specifies the name of this tc Runtime service. Within the scope of a tc Runtime , the service name must be unique. This is the name that 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. See the following documentation on the Apache Web site for additional detailed information:

General

Field Name Description
Protocol Specifies the protocol that handles incoming and outgoing messages for this connector. This field can have the following values:
  • org.apache.coyote.http11.Http11Protocol (same as HTTP/1.1). This is the default value. Note that if you want to use HTTPS, you do not specify "HTTPS/1.1", but rather, 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, upon which the listen port defined in the Port attribute will be opened for connections.  If a specific IP address is not specified, server sockets will be created on all IP addresses associated for the server, on the port specified in the Port attribute. 
Port Specifies the TCP port number on which this connector will create a server socket and await incoming connections. Your operating system allows only one server application to listen to a particular port number on a particular IP address, which means that multiple tc Runtime instances running on the same computer must have unique ports. 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 will be 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 amount of pipelined or keep-alive HTTP requests. The default value of this field is 100.
Proxy Host If this connector is being used in a proxy configuration, specifies the server name that is returned from calls to request.getServerName(). See Proxy Support HOW-TOP for more information.
Proxy Port
If this connector is being used in a proxy configuration, specifies the server port that is returned from calls to request.getServerPort(). See Proxy Support HOW-TOP for more information.
Redirect Port
Specifies the port to which a user is redirected if they require a secure connection. If this 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 you want 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 this 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 this connector creates, which in turn determines the maximum number of simultaneous requests that can be handled. If an executor is associated with this 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 Keyword Specifies that only requests from workers with this secret keyword will be accepted.
Use Request Secret Keyword
Specifies whether tc Runtime should generate a random value for the Request Secret Keyword field.

Security/SSL

Field Name
Description
Secure Specifies whether you want user calls to request.isSecure() to return true for requests received by this connector. Check this field for connectors (both SSL and non-SSL) that receive data from an SSL accelerator, like a crypto card, a SSL appliance or even a Web server.
Enable SSL
Enables SSL traffic (handshake/encryption/decription) for this connector. When enabled, be sure to also set the "scheme" and "secure" attributes so that correct values are returned to user calls to request.getScheme() and request.isSecure(). See SSL Support for more information. 
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 pathname of the keystore file that contains the server certificate to be loaded. By default, the pathname 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.

APR SSL Settings

These settings are only relevant for APR based connectors that also use SSL.

Field Name
Description
SSL Protocol
Specifies the protocol that tc Runtime might use to communicate with clients. Valid values are "SSLv2", "SSLv3", "TLSv1", and "SSLv2+SSLv3". Default value is "all".
SSL Cipher Suite
Specifies the ciphers that tc Runtime might use to communicate with clients. Valid values is a list of ciphers, separated by a colon.

Default value is "all". See the OpenSSL Web site for the list of valid ciphers. 
SSL Certificate File
Specifies the name of the file that contains the server certificate. The format is PEM-encoded.
SSL Certificate Key File Specifies the name of the file that contains the server private key. The format is PEM-encoded. The default value is the value of the SSL Certificate File field, which implies that both the certificate and the private key are in the same file. For security reasons, this is not recommended.
SSL Password
Specifies the password for the encrypted private key. If this field is left blank, the callback function prompts for the password.
SSL Verify Client
Specifies whether tc Runtime should ask client for certificate. The default value is "none", which means that the client will not have the opportunity to submit a certificate. Other valid values include "optional", "require" and "optionalNoCA".
SSL Verify Depth
Specifies the maximum verification depth for client certificates. The default value is "10". 
SSL CA Certificate File
Specifies the single file where you assemble the certificates of Certification Authorities (CA) for the clients that you authenticate. The file is the concatenation of the various PEM-encoded Certificate files, in order of preference. See Apache Module mod_ssl for more information. 
SSL CA Certificate Path
Specifies the directory where you keep the Certificates of Certification Authorities (CAs) for the clients that you authenticate. These are used to verify the client certificate on Client Authentication.
The files in this directory must be PEM-encoded and are accessed through hash filenames. So usually you can't just place the Certificate files there: you also have to create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links. Use the Makefile which comes with mod_ssl to accomplish this task. See Apache Module mod_ssl for more information.
SSL Certificate Chain File Specifies the optional all-in-one file where you can assemble the certificates of Certification Authorities (CA) which form the certificate chain of the server certificate. This starts with the issuing CA certificate of of the server certificate and can range up to the root CA certificate. Such a file is simply the concatenation of the various PEM-encoded CA Certificate files, usually in certificate chain order. See Apache Module mod_ssl for more information.
SSL CA Revocation File
Specifies the directory where you keep the Certificate Revocation Lists (CRL) of Certification Authorities (CAs) whose clients you deal with. These are used to revoke the client certificate on Client Authentication. See Apache Module mod_ssl for more information.
SSL CA Revocation Path
Specifies the directory where you keep the Certificate Revocation Lists (CRL) of Certification Authorities (CAs) whose clients you deal with. These are used to revoke the client certificate on Client Authentication. See Apache Module mod_ssl for more information.

Engine Properties

A tc Runtime engine represents the entire request processing machinery 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 exactly one engine.

Field Name Description
Name Specifies the name of this 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. This name corresponds to the name of a Host component that processes requests directed to host names on this server, but which are not explicitly configured for this 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 participate in a cluster, is appended to the generated session identifier, therefore 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 then clients begin connecting and using the application, you might find that the clients occasionally run into problems such as slow requests or even failed requests. Although tc Runtime by default logs these errors in the log files, it is often difficult to pinpoint where exactly the error came from and how to go about fixing it. By enabling thread diagnostics, tc Runtime provides additional information to help you troubleshoot the problem.

A failed request is one that simply did not execute; a slow request is defined as a request that takes longer 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 happened.
  • 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.
Field Name
Description
Enable Thread Diagnostics
Enables the gathering of thread diagnostic information; see the thread diagnostics introduction for details about the information that tc Runtime gathers.

To view this information after you have enabled thread diagnostics, go to the Monitor tab of a particular tc Runtime instance, then click on 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 presented in the HQ 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 (such as "www.mycompany.com" associated with the particular 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.

Field Name
Description
Name
Specifies the network name of this 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. See Host Name Aliases for information on how to assign more than one network name to the same virtual host.
Application Base Directory Specifies the application base directory for this virtual host. The application base directory may contain Web applications to be deployed on this virtual host. You can specify an absolute pathname for this directory, or a pathname that is relative to the $CATALINA_BASE directory. See Automatic Application Deployment for more information on automatic recognition and deployment of Web applications.
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. See Automatic Application Deployment for more information. 
Deploy Applications on Startup
Specifies whether Web applications from this host should be automatically deployed when the tc Runtime instance starts up. See Automatic Application Deployment for more information.
Unpack WARs Specifies whether tc Runtime should unpack Web applications that are copied to the application base directory as Web application archive (WAR) files into a corresponding disk directory structure. If unchecked, tc Runtime runs the Web applications directory from a WAR file. See Automatic Application Deployment for more information. 
Deploy XML
Specifies whether tc Runtime should parse the "context.xml" file embedded inside the Web application (located at /META-INF/context.xml). Security consious environments should set this to false (uncheck) to prevent applications from interacting with the container's configuration. The administrator will then be responsible for providing an external context configuration file, and put it in $CATALINA_BASE/conf/enginename/hostname/.
Work Directory Specifies the pathname to a scratch directory used by applications for this Host. Each application will have its own sub directory with temporary read-write use. Configuring a Context work directory overrides use of the Host work directory configuration. This directory will be made visible to servlets in the Web application by a servlet context attribute (of type java.io.File) named javax.servlet.context.tempdir as described in the Servlet Specification. If not specified, a suitable directory underneath $CATALINA_BASE/work will be 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 logging files are rolled over nightly at midnight.

Field Name
Description
Enable Logging
Specifies whether you want to enable logging on this engine or virtual host.
Directory Specifies the absolute or relative pathname of a directory in which tc Runtime creates the log files 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 identifying the various information fields from the request and response to be logged, or the word "common" or "combined" to select a standard format. See the Apache Web site for more information on configuring this attribute. Note that the optimized access does only support "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, then set this value to: yyyy-MM-dd.HH
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.