Basics of Server Operation

The configuration and behavior of Sun ONE Application Server is determined by a set of configuration files. When you use the Administration interface, you change the settings in these configuration files. You can also manually edit these files.

This module has the following sections:

• Configuration Files
• Dynamic Reconfiguration
• Manually Editing Configuration Files

Configuration Files

---

The 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. These files are:

• 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, see "Other Configuration Files."

server.xml

This file contains most of the server configuration. A schema file, sun-server_1_0.dtd, defines its format and content.

For more information about how the server uses sun-server_1_0.dtd and server.xml, see "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.

See "Syntax and Use of init.conf" for a list of all the variables and Init directives that can be set in 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 plugins and CGI programs. 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. Editing one of these files directly or through the Administration interface changes the configuration of a virtual server.

The obj.conf file is essential to the operation of the Sun ONE Application Server. When you make changes to the server through the Administration interface, the system automatically updates obj.conf.

The file obj.conf contains a series of instructions (directives) that tell the Sun ONE Application Server what to do at each stage in the request-response process.

For 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 "MIME Types."

Dynamic Reconfiguration

---

You do not have to restart the server for changes to these files to take effect:

• obj.conf
• mime.types
• ACL files
• server.xml (applications and resources subelements only)

However, with the exception of deployment, you must apply the changes for those changes to take effect. You can use the Administration interface as follows:

1. Go to the server instance page.
2. Select the General tab.
3. Select the Apply Changes button.

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 that contains all the information from the dynamically configurable files is loaded into memory.

---

Note

Sometimes when you apply configuration changes, the server instance displays an error message. For example, when security is turned on and you apply changes, you may see an Invalid configuration error. If this happens, restart the instance as soon as a restart message such as Instance restart is required or Server restart needed is displayed. Deferring the restart may cause similar error messages to be shown repeatedly.

---

Manually Editing Configuration Files

---

Manually editing configuration files is not recommended. Here are some cautionary guidelines for manually editing configuration files:

• Edit only the files in the instance_dir/config directory. Do not copy files to the backup directory or remove the timestamp files (which prevent overwriting of manual changes).
• If you have made both manual changes and changes through the Administration interface 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.
• Use the --keepmanualchanges or --discardmanualchanges option of the asadmin reconfig command to make the same choice at the command line. For example:

asadmin reconfig --user joeuser --password secret --keepmanualchanges=true server1

To avoid this dilemma, always apply changes immediately after making them, and don't mix manual and Administration interface changes.

• Do not manually edit a file and then restart the server. Use the --keepmanualchanges option of the asadmin reconfig command before restarting the server. See the example above.
• Whenever the configuration in server.xml is modified using the Administration interface, it is always validated against the sun-server_1_0.dtd file. Additional validation is done that pertains to checking the file's cross-references. Make sure your configuration is complete and correct before applying it.
• When you modify applications or resources subelements of server.xml (for example, you deploy a J2EE application or register a JDBC Connection Pool), the Administration Server attempts to apply the changes to a running server instance. Make sure your configuration is complete and correct before applying it.
• 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.