test

Sun Java System Web Server 7.0 Update 7 Administrator's Configuration File Reference

Chapter 2 Syntax and Use of server.xml

The server.xml file contains most of the server configuration. This chapter describes the basic syntax of server.xml and gives a high-level view of the elements that configure server features. It contains the following sections:

Overview of server.xml

The server.xml file contains most of the configuration information needed to run the server. The server.xml file is located in the instance_dir/config directory. The encoding is UTF-8 to maintain compatibility with regular UNIX text editors.

sun-web-server_7_0.xsd

The sun-web-server_7_0.xsd schema validates the format and content of the server.xml file. The schema enforces type checks. For example, it ensures that the ip element specifies a valid IP address. The sun-web-server_7_0.xsd file is located in the install_dir/lib/dtds directory.

Editing server.xml

The structure of server.xml 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 Admin Console and the wadm command-line interface to change values in server.xml. Using wadm when creating scripts to change server.xml assures you of forward compatibility. If you do edit server.xml directly, exercise caution to make sure that the resulting server.xml file is valid.

Editing Element Values

To change the values in server.xml, change the value between the tags associated with the element you are editing. For example, to change the log level from info to fine, find the log child element of the server element. In this example, you see the following lines:

  <log>
    <log-file>../logs/errors</log-file>
    <log-level>info</log-level>
  </log>

To change the log level from info to fine, change the line:

<log-level>info</log-level>

to:

<log-level>fine</log-level>

After you make changes to the server.xml file, you must deploy your configuration for most changes to take effect. Use the command-line interface command wadm pull-config to pull the modified server.xml file, then use the Admin Console or the wadm deploy-config command to deploy your changes. For some changes, you must restart the server before they take effect. For information on which changes require a restart and which do not, see Dynamic Reconfiguration.

Adding Elements

To add a new element to sever.xml, 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.

Validating server.xml

After editing server.xml, Web Server automatically validates the XML when you start or dynamically reconfigure a the server.

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

startserv –configtest

Understanding server.xml

To edit server.xml 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:

In addition, Chapter 3, Elements in server.xml contains an alphabetical list of all the server.xml elements and their subelements.

Access Control

The acl-file element references an ACL file. ACL files define the authorization rules. The auth-realm and default-auth-realm-name elements configure authentication realms for Java Servlet container authentication. For more information, see acl-file, auth-realm, and default-auth-realm-name.

The auth-db and default-auth-db-name elements configure the authentication databases for server authentication. Authentication databases are used with ACL files. For more information, see auth-db, and default-auth-db-name.

For more information on ACL files, see Chapter 9, ACL Files.

Clustering

The cluster element defines a cluster of servers to which an individual server instance belongs. The instance element defines an individual member of a cluster. The session-replication element configures how Java Servlet sessions are shared between instances in a cluster. For more information, see cluster, instance, and session-replication.

HTTP Protocol

The http element configures the general HTTP protocol options. The keep-alive element configures 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 how the server processes the HTTP requests. For more information, see http, keep-alive, http-listener, and virtual-server.

Java

The following elements configure the Java Servlet container:

The following elements configure the Java Naming and Directory InterfaceTM (JNDI) resources:

The lifecycle-module element loads the custom Java plug-ins that are triggered by one or more events in the server's lifecycle. For more information lifecycle-module.

The soap-auth-provider element configures message-level authentication for Java web services. For more information, see soap-auth-provider.

The jvm element configures the Java Virtual Machine (JVM). For more information, see jvm.

Logging and Monitoring

The access-log element configures the file name and formats 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 access-log and access-log-buffer.

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 log and event.

The snmp element configures SNMP, and the stats element configures statistics collection. For more information, see snmp and stats.

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 thread-pool.

The keep-alive element configures the HTTP keep-alive connection management. For more information, see keep-alive.

WebDAV ACL, lock, and property caching are controlled by the acl-db, lock-db, and property-db elements, respectively. For more information, see acl-db, lock-db, and property-db.

The file-cache element configures file caching. The dns-cache element configures the DNS caching. The acl-cache element configures the authentication credential caching. For more information, see file-cache, dns-cache, and acl-cache.

Search

The search-collection element defines the set of documents that the server should index. The search-app element configures the server's built-in search web application. For more information, see search-collection and search-app.

SSL, TLS, and PKCS #11

The ssl element configures SSL and TLS. SSL and TLS can be configured separately for each HTTP listener. For more information, see ssl and http-listener.

The pkcs11 element configures the PKCS #11 subsystem, including Certificate Revocation Lists (CRLs) and third-party cryptographic modules. For more information, see pkcs11.

Variables

The variable element defines a variable for use in expressions, log formats, and obj.conf parameters. For more information on the variable element, see variable. For more information on variable and expression use, see Appendix A, Using Variables, Expressions, and String Interpolation. For more information on the log file format, see Appendix C, Using the Custom Log File Format.

Virtual Servers

The virtual-server element configures the virtual servers. Each virtual server accepts HTTP connections from one or more HTTP listeners. The http-listener element configures the HTTP listeners. For more information, see virtual-server, and http-listener.

You can define variables within a virtual server using the variable element, as described in the previous section, Variables.

WebDAV

The dav element configures WebDAV. The dav-collection element defines the set of files that are accessible through WebDAV. For more information, see dav and dav-collection.

Sample server.xml File

The following example shows a server.xml file.

Example 2–1 server.xml File

?xml version="1.0" encoding="UTF-8"?>

<!--
  Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
  Use is subject to license terms.
-->

<server>
  <cluster>
    <local-host>sun1</local-host>
    <instance>
      <host>sun1</host>
    </instance>
  </cluster>

  <log>
    <log-file>../logs/errors</log-file>
    <log-level>info</log-level>
  </log>

  <temp-path>/tmp/https-sun1-5351d5c9-2</temp-path>

  <user>myuser/user>

  <jvm>
    <java-home>/opt/webserver7/jdk</java-home>
    <server-class-path>/opt/webserver7/lib/webserv-rt.jar:/opt/webserver7/lib/pw
c.jar:/opt/webserver7/lib/ant.jar:${java.home}/lib/tools.jar:/opt/webserver7/lib
/ktsearch.jar:/opt/webserver7/lib/webserv-jstl.jar:/opt/webserver7/lib/jsf-impl.
jar:/opt/webserver7/lib/jsf-api.jar:/opt/webserver7/lib/webserv-jwsdp.jar:/opt/w
ebserver7/lib/container-auth.jar:/opt/webserver7/lib/mail.jar:/opt/webserver7/li
b/activation.jar</server-class-path>
    <debug>false</debug>
    <debug-jvm-options>-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,
address=7896</debug-jvm-options>
    <jvm-options>-Djava.security.auth.login.config=login.conf</jvm-options>
    <jvm-options>-Djava.util.logging.manager=com.sun.webserver.logging.ServerLog
Manager</jvm-options>
    <jvm-options>-Xms128m -Xmx256m</jvm-options>
  </jvm>

  <thread-pool>
    <max-threads>128</max-threads>
    <stack-size>131072</stack-size>
  </thread-pool>

  <default-auth-db-name>keyfile</default-auth-db-name>

  <auth-db>
    <name>keyfile</name>
    <url>file</url>
    <property>
      <name>syntax</name>
      <value>keyfile</value>
    </property>
    <property>
      <name>keyfile</name>
      <value>keyfile</value>
    </property>
  </auth-db>

  <acl-file>default.acl</acl-file>

  <mime-file>mime.types</mime-file>

  <access-log>
    <file>../logs/access</file>
  </access-log>

  <http-listener>
    <name>http-listener-1</name>
    <port>8082</port>
    <server-name>sun1</server-name>
    <default-virtual-server-name>sun1</default-virtual-server-name>
  </http-listener>

  <virtual-server>
    <name>sun1</name>
    <host>sun1</host>
    <http-listener-name>http-listener-1</http-listener-name>
  </virtual-server>
</server>