| Sun ONE Application Server 7, Enterprise Edition Administrator's Configuration File Reference |
Chapter 1
Basics of Server OperationThe configuration and behavior of Sun™ Open Net Environment (Sun ONE) Application Server 7, Enterprise Edition, is determined by a set of configuration files. When you use the Administration interface or the command line, you change settings in these configuration files behind the scenes.
This chapter has the following sections:
Configuration FilesThe configuration and operation of the Sun ONE Application Server is controlled by configuration files. The configuration files reside in the directory instance_dir/config. This directory contains various configuration files for controlling different components. The exact number and names of configuration files depends on which components have been enabled or loaded into the server.
However, this directory always contains four configuration files that are essential for the server to operate:
- server.xml - contains most of the server configuration.
- init.conf - contains global server initialization information.
- obj.conf - contains instructions for handling HTTP requests from clients.
- mime.types - contains information for determining the content type of requested resources.
For information about other important configuration files, such as dbswitch.conf and loadbalancer.xml, see Chapter 5, “Other Configuration Files.”
server.xml
This file contains most of the server configuration. A schema file, sun-server_1_1.dtd, defines its format and content. For more information about how the server uses sun-server_1_1.dtd and server.xml, see Chapter 2, “Server Configuration Files.”
init.conf
This file sets values of variables that configure the server during initialization. The server looks at this file and executes the settings on startup. The server does not look at this file again until it is restarted. For more information about how the server uses init.conf, see Chapter 3, “Syntax and Use of init.conf.”
obj.conf
This file contains instructions for the server about how to process HTTP requests from clients and service web server content such as native server plug-ins and CGI programs. The file’s directives tell the Sun ONE Application Server what to do at each stage in the request-response process. The server looks at the configuration defined by this file every time it processes a request from a client.
All obj.conf files are located in the instance_dir/config directory. There is one obj.conf file for each virtual server, unless several virtual servers are configured to share an obj.conf file. Whenever this guide refers to “the obj.conf file,” it refers to all obj.conf files or to the obj.conf file for the virtual server being described.
The file named obj.conf that lacks a prefix is a template that Sun ONE Application Server uses to create obj.conf files for each virtual server. Editing this file does not affect any existing virtual servers, but does affect any subsequently created virtual servers.
By default, each active obj.conf file is named virtual_server_name-obj.conf. Because the default virtual server for a server instance is named after the instance, when you first create a server instance, its obj.conf file is named instance_name-obj.conf.
For detailed information about how the server uses obj.conf, see the Sun ONE Application Server Developer’s Guide to NSAPI.
mime.types
This 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 how the server uses mime.types, see Chapter 4, "MIME Types."
Dynamic ReconfigurationChanges take effect immediately when you change the applications and resources elements of the server.xml file (for example, you deploy a Java™ 2 Platform, Enterprise Edition (J2EE™ platform) application or register a Java™ Database Connectivity (JDBC™) Connection Pool). You do not need to restart the server or apply the changes.
You can set up the loadbalancer.xml file so that changes to it take effect immediately by changing its reload-poll-interval-in-seconds property. For details, see “loadbalancer.xml”.
When you change the following files, you do not need to restart the server for the changes to take effect, but you must apply the changes:
To apply the changes, you can use the Administration interface as follows:
Or you can use the command line as follows:
asadmin reconfig --user user [--password password] [--passwordfile password_file] [--host machine] [--port port] [--discardmanualchanges=false | --keepmanualchanges=false] instance_name
For example:
asadmin reconfig --user joeuser --password secret --keepmanualchanges=true server1
When you change the configuration and apply the changes, the new configuration, which contains all the information from the dynamically configurable files, is loaded into memory.
Manually Editing Configuration FilesWhen you change the server instance using the Administration interface or the command line, these changes are held in memory. When you apply the changes, they are written to the configuration files behind the scenes.
When you change the server instance by manually editing configuration files, the server instance does not recognize the changes until you apply them.
Therefore, if you make both kinds of changes without applying them, you must keep one set of changes and discard the other. Because of this possibility of overwriting changes, manually editing configuration files is risky.
The loadbalancer.xml file is an exception; it can only be edited manually. For details, see “loadbalancer.xml”.
Here are some cautionary guidelines for manually editing configuration files:
- If you have made both kinds of changes without applying them, you have the following alternatives:
- Apply the changes using the Administration interface, which forces you to choose between your manual and Administration interface changes.
- Apply the changes using the asadmin reconfig command, and use the --keepmanualchanges or --discardmanualchanges option to choose. If you don’t use either option, manual changes are discarded. For example:
asadmin reconfig --user joeuser --password secret --keepmanualchanges=true server1
- Edit only the files in the instance_dir/config directory. Do not copy files to the server’s backup directory or remove the timestamp files (which prevent overwriting of manual changes). However, making your own backup files before making manual changes is a good practice, in case your changes result in an incorrect configuration.
- Whenever the configuration in server.xml is modified using the Administration interface, it is always validated against the sun-server_1_1.dtd file. Additional validation is done that pertains to checking the file’s cross-references. If you manually edit server.xml, it is up to you to make sure the configuration is complete and correct.
- When you manually edit applications or resources subelements of server.xml, the changes take effect immediately. You do not need to apply the changes. Although in this case you don’t have to worry about future changes overwriting these changes, it is especially important to make sure the configuration is complete and correct.
- If you have made manual changes, you must apply those changes before restarting the server.
- The Administration Server remembers unapplied changes across its own restarts. Therefore, at times the Administration Server may have a view of a server instance’s configuration that is not the same as the actual configuration of the server instance. To avoid this inconsistency, always apply changes to all server instances before restarting the Administration Server.
Reconfiguring a ClusterTo change the configuration of a cluster of server instances, use the cladmin command. This command can perform the following operations on a cluster:
For details, see the Sun ONE Application Server Administrator’s Guide.
