2 Syntax and Use of server.xml

The server.xml file contains most of the server configuration. This chapter describes the basic syntax of the server.xml file and provides a high-level view of the elements that are used to configure features of the server. This chapter contains the following topics:

2.1 Overview of server.xml

The server.xml file contains the elements that define the configuration. The server.xml file is located in the
INSTANCE_HOME/net-server-id/config directory.

The file encoding is UTF-8 to maintain compatibility with UNIX text editors.

2.1.1 Editing the server.xml File

The structure of the server.xml file is a hierarchy, with server as the topmost element. The server element has many subelements, many of which have subelements of their own.

In general, you do not need to edit server.xml directly. Instead, use the Administrator Console and the tadm command-line interface to change values in the server.xml file. Changes made using the Administrator Console and tadm command-line interface affect the server.xml file. Using tadm when creating scripts to change the server.xml file ensures forward compatibility. If you edit the server.xml file directly, ensure that the resulting server.xml file is valid.

2.1.1.1 Editing Element Values

To change the values in the server.xml file, change the value between the tags associated with the element you are editing. For example, to change the value of
<log-level> from NOTIFICATION:1 to TRACE:1, find the log child element of the server element. In this example, you see the following lines:

  <log>
    <log-file>../logs/server.log</log-file>
    <log-level>NOTIFICATION:1</log-level>
  </log>
For example:

Change the log-level from NOTIFICATION:1

<log-level>NOTIFICATION:1</log-level>

to TRACE:1

<log-level>TRACE:1</log-level>

After altering the server.xml file, you must deploy your configuration for most changes to take effect. Use the command-line interface command tadm pull-config to pull the modified server.xml file, then use the Administrator Console or the tadm deploy-config command to deploy your changes. Some changes require a server restart in order to take effect. For information about changes that require a restart and which do not, see Section 1.3, "Dynamic Reconfiguration".

2.1.1.2 Adding Elements

To add a new element to the file, add the element and any required subelements. Elements begin with a tag, for example <virtual-server>, and end with the closing tag, for example </virtual-server>. The tags are case-sensitive.

2.1.1.3 Validating server.xml

After editing the server.xml file, Oracle Traffic Director automatically validates the XML code when you start or dynamically reconfigure a server.

You can also use the -configtest option of the startserv script to validate your configuration. From the instance's bin directory, run:

startserv -configtest

2.2 Understanding server.xml

To change the server.xml file for your environment, you must know which elements contain the relevant settings. The following sections contain brief descriptions of the elements that configure the functional areas:

For more information about all the server.xml elements and their subelements, see Elements in server.xml.

2.2.1 Server Pools

The origin-server element defines a member of a server pool. The origin-server-pool element configures a pool of origin servers that are used to load-balance requests. An origin server is a back-end server—such as an Oracle WebLogic Server instance or an Oracle iPlanet Web Server instance—to which Oracle Traffic Director should forward requests that it receives from clients, and from which it receives responses. A set of origin servers providing the same service constitute an origin server pool. For more information, see Section 3.1.21, "origin-server-pool", Section 3.1.22, "origin-server", Section 3.1.26, "server"

2.2.2 Health check

The health-check element configures the parameters that are used to determine the status of each origin server in an origin-server pool. The health-check element is a subelement of the origin-server-pool element. For more information, see Section 3.1.13, "health-check" and Section 3.1.21, "origin-server-pool"

2.2.3 High Availability

The failover-group element is a grouping of a VIP (Virtual IP), an instance that is designated as the primary server and another instance designated as the backup server. The Active-Passive or Active-Active cluster failover configurations are represented as Failover Groups. The failover-group element defines a failover group. For more information, see Section 3.1.11, "failover-group"

2.2.4 HTTP Protocol

The http element configures the general HTTP protocol options. The keep-alive element configures the HTTP keep-alive connection management. The http-listener element configures the ports and IP addresses on which the server listens for new HTTP connections. The virtual-server element configures a method by which the server processes the HTTP requests. For more information, see Section 3.1.14, "http", Section 3.1.17, "keep-alive", Section 3.1.15, "http-listener", and Section 3.1.40, "virtual-server".

2.2.5 Logging and Monitoring

The access-log element configures the file name and format of access logs. The access-log-buffer element configures the frequency of access log updates and ordering of the access log entries. For more information, see Section 3.1.1, "access-log" and Section 3.1.2, "access-log-buffer". For more information about the log file format, see Appendix B, "Using the Custom Access-Log File Format".

The log element configures the file name and contents of the server log. The event element configures the access log and server log rotation. For more information, see Section 3.1.19, "log" and Section 3.1.9, "event".

The snmp element configures Simple Network Management Protocol (SNMP), and the stats element configures statistics collection. For more information, see Section 3.1.27, "snmp" and Section 3.1.31, "stats".

2.2.6 Performance Tuning

The thread-pool element configures the number of threads used to process requests and the maximum number of HTTP connections that the server queues. For more information, see Section 3.1.37, "thread-pool".

The keep-alive element configures the HTTP keep-alive connection management. For more information, see Section 3.1.17, "keep-alive". The dns-cache element configures the DNS caching. For more information, see Section 3.1.8, "dns-cache".

2.2.7 SSL, TLS, and PKCS #11

The ssl element configures Secure Sockets Layer (SSL) and Transport Layer Security (TLS). SSL and TLS can be configured separately for each HTTP listener. For more information, see Section 3.1.28, "ssl" and Section 3.1.15, "http-listener".

The pkcs11 element configures the PKCS #11 subsystem, including certificate revocation lists (CRLs) and third-party cryptographic modules.

2.2.8 Variables

The variable element defines a variable for use in expressions, log formats, and obj.conf parameters. For more information about the variable element, see Section 3.1.39, "variable". For more information about variable and expression use, see Appendix A, "Using Variables, Expressions, Wildcards, and String Interpolation".

2.2.9 Virtual Servers

The virtual-server element configures the virtual servers. Each virtual server processes HTTP requests from one or more HTTP listeners. The http-listener element configures the HTTP listeners. For more information, see Section 3.1.40, "virtual-server", and Section 3.1.15, "http-listener".

You can define variables within a virtual server using the variable element, as described in Section 2.2.8, "Variables".

2.3 Sample server.xml File

Example 2-1 shows an excerpt from a server.xml file.

Example 2-1 server.xml file

<?xml version="1.0" encoding="UTF-8" ?>
 
<!--
  Copyright (c) 2011, Oracle and/or its affiliates. All rights reserved
-->
 
<server>
  <cluster>
    <local-host>www.example.com</local-host>
    <instance>
      <host>www.example.com</host>
    </instance>
  </cluster>
  <log>
    <log-file>../logs/server.log</log-file>
    <log-level>NOTIFICATION:1</log-level>
  </log>
  <platform>64</platform>
  <temp-path>/tmp/net-test-8a4af444</temp-path>
  <user>myuser</user>
  <access-log>
    <file>../logs/access.log</file>
  </access-log>
 <http-listener>
   <name>http-listener-1</name>
   <port>1894</port>
   <server-name>www.example.com</server-name>
   <default-virtual-server-name>test</default-virtual-server-name>
  </http-listener>
 <virtual-server>
    <name>test</name>
    <http-listener-name>http-listener-1</http-listener-name>
    <host>www.example.com</host>
    <object-file>test-obj.conf</object-file>
 </virtual-server>
 <origin-server-pool>
    <name>origin-server-pool-1</name>
    <type>http</type> 
 <origin-server>
    <host>www.example.com</host> 
    <port>20005</port> 
    </origin-server>
   </origin-server-pool>
  </server>