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

Chapter 1 Overview of Configuration Files and Directories

The configuration and behavior of Sun Java System Web Server 7.0 (Web Server) is determined by a set of configuration files. You can use the Admin Console and the command-line interface (CLI) to change the configuration file settings. You can also manually edit these files.

This chapter has the following sections:

Configuration Files

Each server instance has its own directory, called instance_dir in this document. The instance_dir/config directory contains configuration files for the Web Server components. The exact number and names of the configuration files depend on the components that have been enabled or loaded into the server. For the default location of the instance_dir, see Default Paths and File Names.

These files, as well as some other configuration files not included in the config directory, are described in the following sections:

The server.xml File

The server.xml file contains most of the server configuration. A schema file, sun-web-server_7_0.xsd, validates its format and content. For more information about sun-web-server_7_0.xsd and the various elements of server.xml, see Chapter 2, Syntax and Use of server.xml and Chapter 3, Elements in server.xml.

The magnus.conf File

The magnus.conf file contains the NSAPI plug-in initialization directives and settings that control the way NSAPI plug-ins are run. For more information about magnus.conf, see Chapter 4, Syntax and Use of magnus.conf and Chapter 5, Predefined SAFs in magnus.conf.

The obj.conf File

The obj.conf file contains directives for HTTP request processing. For more information about obj.conf, see Chapter 6, Syntax and Use of obj.conf and Chapter 7, Predefined SAFs and Filters in obj.conf.

The mime.types File

The mime.types file maps file extensions to MIME types to enable the server to determine the content type of a requested resource. For example, requests for resources with .html extensions indicate that the client is requesting an HTML file, while requests for resources with .gif extensions indicate that the client is requesting an image file in GIF format. For more information about mime.types, see Chapter 8, MIME Types.

ACL Files

The Access Control List (ACL) files contain lists that define who can access resources stored on your Web Server. By default, Web Server uses one ACL file. You can create multiple ACL files and reference them in the obj.conf and server.xml files. For more information about ACL files, see Chapter 9, ACL Files.

Other Configuration Files

Other configuration files for administration and for applications include the certmap.conf, sun-web.xml, login.conf, server.policy, and default-web.xml. For more information on these files, see Chapter 10, Other Server Configuration Files.

Directory Structure

This section describes the directory structure that is created when you first install Sun Java System Web Server. In a stand-alone Web Server installation, all these directories are in the install_dir by default. In Web Servers installed as part of Java Enterprise System, the instance directories (which in this case includes both admin-sever and https-sever_id) are in a different location. For more information on the default locations for these directories on different platforms, see the information on instance_dir in Default Paths and File Names.

admin-server

The admin-server directory has the following subdirectories:

bin – Contains the binary files that are required to start, stop, and restart Web Server. On UNIX systems, this directory also contains the file required for rotating logs.
config – Contains the private configuration files for the Administration Server. These files are for internal use.
config-store – Contains files used by the Administration Server to track server configuration information.

Note –
The files in this directory are created by Web Server for internal use. Do not edit, run scripts on, or otherwise access any files in the config-store directory.
generated – Contains files generated by the instance, such as Java class files corresponding to JavaServer Pages^TM (JSP^TM).
logs – Contains any error or access log files that are generated by a server instance.
sessions – Contains session data files.

bin

The bin directory contains the binary files for administering Web Server. These files include wadm, the administration command-line interface (CLI).

https-server_id

An https-server_id directory is created for every instance you create. This directory has the following subdirectories and files:

bin – Contains the binary files for starting, stopping, restarting, and reconfiguring the server. On UNIX, it also contains the binary file for rotating the log files.
collections – Contains the search collection data.
config – Contains the following instance-specific configuration files:
- cert8.db – NSS certificate database
- certmap.conf – Certificate to LDAP DN mapping configuration
- default.acl – Default ACL file for the server instance named server_id
- default-web.xml – Default values for all web applications
- key3.db – NSS private key database
- keyfile – The usernames and hashed passwords for flat file authentication
- login.conf – Information for file authentication used by the Java Authentication and Authorization Service (JAAS)
- magnus.conf – Information for NSAPI plug-in initialization and operation
- mime.types – Map of file extensions to MIME types that enables the server to determine the content type of a requested resource
- obj.conf – Instructions for Web Server for handling HTTP requests from clients
- secmod.db – NSS PKCS #11 module database
- server.policy – Policy controlling the access that applications have to resources
- server.xml – Most of the server configuration settings
docs – Contains the files in the default document root for an instance.
generated – Contains files generated by the instance.
lock-db – The default directory for WebDAV lock database files.
logs – Contains log files generated by a server instance.
sessions – Contains session data files.
web-app – The default directory for deployed web applications.

include

The include directory contains the various include files, for example, NSAPI and SHTML include files.

jdk

The jdk directory contains the bundled Java development kit (JDK^TM). For stand-alone installations only.

lib

The lib directory contains internal binaries, scripts, libraries, and bundled plug-ins. These files are private files, for internal use only.

plugins

The plugins directory contains the plug-in subdirectories. .

digest contains the digest authentication plug-in for Sun Java Directory Server, as well as information about the plug-in.
fastcgi contains the files for the FastCGI plug-in.
htaccess contains server plug-in for .htaccess access control and htconvert, which is an .nsconfig to .htaccess converter.
loadbal contains the required files for the third–party load-balancer integration plug-in.

For more information on these plug-ins, see Sun Java System Web Server 7.0 Update 3 Administrator’s Guide.

samples

The samples directory contains samples and example components, plug-ins, and technologies supported by the Sun Java System Web Server Servlet engine. This includes binaries, all code, and a build environment.

setup

The setup directory contains the various Web Server setup files, including the installation logs.

Dynamic Reconfiguration

Dynamic reconfiguration allows you to make configuration changes to a runtime Web Server. You do not have to stop or restart the Web Server for the changes to take effect.

Dynamic configuration happens in one of the following ways:

When you deploy a configuration through the Admin Console or CLI
When you run the reconfig script in the server instance's bin directory

You can dynamically change the configuration settings in the obj.conf, mime.types, and ACL files without restarting the server. In addition, most settings in the server.xml file can be changed without restarting the server. If a server restart is required, a warning message appears in the server log when you deploy the configuration or run the reconfig command.

You cannot dynamically reconfigure the following server.xml configuration parameters:

user
temp-path
log (with the exception of log-level)
thread-pool
pkcs11
stats
cgi
dns
dns-cache
file-cache
acl-cache
ssl-session-cache
access-log-buffer
jvm (with exception of log-level)

When you run the reconfig command, a new configuration object is created and allnew incoming requests are processed based on this new configuration object. The current configuration object gets removed when no HTTP requests are using the object. For example, if you are using Web Server with reverse proxy in the front-end can dynamically add a new back-end server and apply the reconfiguration by using the reconfig command.

The following additional configuration changes within server.xml are supported by the reconfig command:

Add a new HTTP listener
Add a new Java web application

Note –
If the web application requires changes to the JVM or require a new JDBC resource, then you must restart the server instead of using the reconfig command.

Note –

Some configuration changes cannot be instantly propogated to the running server. For example, adding a JVM property of a resource.

If a misconfiguration occurs during dynamic reconfiguration, the server displays an error message. The server logs the error message to a log file specified by the previous known good configuration.

Certain misconfigurations result in warning messages but do not cause the server to reject the configuration. Other misconfigurations result in error messages and cause the server to reject the configuration. If the server rejects a configuration during startup, the server does not start. If the server rejects a configuration during dynamic reconfiguration, the server reverts to the previous known good configuration.