Sun Java System Web Proxy Server 4 Administrator's Configuration File Reference |
Chapter 2
Server Configuration Elements in server.xmlThe server.xml file contains most of the server configuration. The encoding is UTF-8 to maintain compatibility with regular UNIX text editors. The server.xml file is located in the <Instance_Directory>/config directory. A schema file, sun-web-proxy-server_4_0.dtd, determines the format and content of the server.xml file.
This chapterdescribes server.xml and sun-web-proxy-server_4_0.dtd in the following sections:
The sun-web-proxy-server_4_0.dtd FileThe sun-web-proxy-server_4_0.dtd file defines the structure of the server.xml file, including the elements it can contain and the subelements and attributes these elements can have. The sun-web-proxy-server_4_0.dtd file is located in the <Install_Directory>/bin/proxy/dtds directory.
Each element defined in a DTD file (which may be present in the corresponding XML file) can contain the following:
Subelements
Elements can contain subelements. For example, the following file fragment defines the VSCLASS element.
<!ELEMENT LS (DESCRIPTION?, SSLPARAMS?)>
The ELEMENT tag specifies that a LSCLASS element can contain DESCRIPTION, and SSLPARAMS elements in that order.
The following table shows how optional suffix characters of subelements determine the requirement rules, or number of allowed occurrences, for the subelements.
If an element cannot contain other elements, you see EMPTY or (#PCDATA) instead of a list of element names in parentheses.
Data
Some elements contain character data instead of subelements. These elements have definitions of the following format:
<!ELEMENT element-name (#PCDATA)>
For example:
<!ELEMENT DESCRIPTION (#PCDATA)>
In the server.xml file, white space is treated as part of the data in a data element. Therefore, there should be no extra white space before or after the data delimited by a data element. For example:
<DESCRIPTION>myserver</DESCRIPTION>
Attributes
Elements that have ATTLIST tags contain attributes (name-value pairs). For example:
<!ATTLIST ACLFILE
id ID #REQUIRED
file CDATA #REQUIRED
An ACLFILE element can contain id, and file attributes.
The #REQUIRED label means that a value must be supplied. The #IMPLIED label means that the attribute is optional, and that Sun Java System Web Proxy Server generates a default value. Wherever possible, explicit defaults for optional attributes (such as "true") are listed.
Attribute declarations specify the type of the attribute. For example, CDATA means character data, and %boolean is a predefined enumeration.
Elements in the server.xml FileThis section describes the XML elements in the server.xml file. Elements are grouped as follows:
For an alphabetical listing of elements in server.xml, see Alphabetical List of Server Configuration Elements.
Core Server ElementsGeneral elements are as follows:
SERVER
Defines a server. This is the root element; there can only be one server element in a server.xml file.
Subelements
The following table describes subelements for the SERVER element.
Attributes
The following table describes attributes for the SERVER element.
PROPERTY
Specifies a property, or a variable that is defined in server.xml and referenced in obj.conf. For information about variables, see Variables.
A property adds configuration information to its parent element that is one or both of the following:
For example,
<PROPERTY name="accesslog" value="<Install_Root>/<Instance_Directory>/logs/access"/>
Subelements
The following table describes subelements for the PROPERTY element.
Table 2-4 PROPERTY subelements
Element
Required
Description
zero or one
Contains a text description of the property.
Attributes
The following table describes attributes for the PROPERTY element.
Table 2-5 PROPERTY attributes
Attribute
Default
Description
name
none
Specifies the name of the property or variable.
value
none
Specifies the value of the property or variable.
DESCRIPTION
Contains a text description of the parent element.
Subelements
none
Attributes
none
LOG
Configures the system logging service, which includes the following log files:
Subelements
The following table describes subelements for the LOG element.
Table 2-6 LOG subelements
Element
Required
Description
zero or more
Specifies a property or a variable.
Attributes
The following table describes attributes for the LOG element.
EVENT
An event can be scheduled to run at (a) specific time(s) either on (a) day(s) of the week or on (a) day(s) of the month or when the server starts up or shuts down.
Subelements
The following table describes subelements for the EVENT element.
Attributes
The following table describes attributes for the EVENT element.
Table 2-9 EVENT attributes
Attribute
Default
Description
enabled
true
Indicates whether the specified event is to be scheduled or not.
name
none
Specifies the name of the event.
EVENTTIME
Container element that specifies the time at which the event is to be executed. This is a required element.
Subelements
The following table describes subelements for the EVENTTIME element.
EVENTACTION
Container element that specifies the event action to be executed.
Subelements
The following table describes subelements for the EVENTACTION element.
Listener ElementsThe Listener elements are as follows:
LS
Defines an HTTP listen socket.
Subelements
The following table describes subelements for the LS element.
Table 2-12 LS subelements
Element
Required
Description
zero or one
Contains a text description of the listen socket.
zero or one
Defines Secure Socket Layer (SSL) parameters.
Attributes
The following table describes attributes for the LS element.
Table 2-13 LS attributes
Attribute
Default
Description
id
none
(optional) The socket family type. A socket family type cannot begin with a number.
When you create a secure listen socket in the server.xml file, security must be turned on in magnus.conf. When you create a secure listen socket in the Server Manager, security is automatically turned on globally in magnus.conf.
ip
any
Specifies the IP address of the listen socket. Can be in dotted-pair or IPv6 notation. Can also be any for INADDR_ANY.
port
none
Port number to create the listen socket on. Legal values are 1 - 65535. On UNIX, creating sockets that listen on ports 1 - 1024 requires superuser privileges. Configuring an SSL listen socket to listen on port 443 is recommended. Two different IP addresses can’t use the same port.
security
false
(optional) Determines whether the listen socket runs SSL. Legal values are on, off, yes, no, 1, 0, true, false. You can turn SSL2 or SSL3 on or off and set ciphers using an SSLPARAMS subelement for this listen socket.
The Security setting in the magnus.conf file globally enables or disables SSL by making certificates available to the server instance. Therefore, Security in magnus.conf must be on or security in server.xml does not work. For more information, see Syntax and Use of magnus.conf.
acceptorthreads
1
(optional) Number of acceptor threads for the listener. The recommended value is the number of processors in the machine. Legal values are 1 - 1024.
family
none
(optional) The socket family type. Legal values are inet, inet6, and nca. Use the value inet6 for IPv6 listen sockets. When using the value of inet6, IPv4 addresses will be prefixed with ::ffff: in the log file. Specify nca to make use of the Solaris Network Cache and Accelerator.
blocking
false
(optional) Determines whether the listen socket and the accepted socket are put in to blocking mode. Use of blocking mode may improve benchmark scores. Legal values are on, off, yes, no, 1, 0, true, false.
servername
none
Tells the server what to put in the host name section of any URLs it sends to the client. This affects URLs the server automatically generates; it doesn’t affect the URLs for directories and files stored in the server. This name should be the alias name if your server uses an alias.
If you append a colon and port number, that port will be used in URLs the server sends to the client.
SSLPARAMS
Defines SSL (Secure Socket Layer) parameters.
Subelements
none
Attributes
The following table describes attributes for the SSLPARAMS element.
MIME
Defines MIME types.
The most common way that the server determines the MIME type of a requested resource is by invoking the type-by-extension directive in the ObjectType section of the obj.conf file. The type-by-extension function does not work if no MIME element has been defined in the SERVER element.
Attributes
The following table describes attributes for the MIME element.
Table 2-15 MIME attributes
Attribute
Default
Description
id
none
Internal name for the MIME types listing. The MIME types name cannot begin with a number.
file
none
The name of a MIME types file. For more information, see MIME Types.
TYPE
Defines the type of the requested resource.
Subelements
none
Attributes
The following table describes attributes for the TYPE element.
ACLFILE
References one ACL file.
Subelements
The following table describes subelements for the ACLFILE element.
Table 2-17 ACLFILE subelements
Element
Required
Description
zero or one
Contains a text description of the ACLFILE element.
Attributes
The following table describes attributes for the ACLFILE element.
USERDB
Defines the user database used by the server.
Subelements
The following table describes subelements for the USERDB element.
Table 2-19 USERDB subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the USERDB element.
Cache ElementsCache elements are as follows:
FILECACHE
Configures the in-memory cache.
Subelements
The following table describes subelements for the FILECACHE element.
Table 2-21 FILECACHE subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the FILEACHE element.
CACHE
Configures the disk cache.
Subelements
The following table describes subelements for the CACHE element.
Attributes
The following table describes attributes for the CACHE element.
PARTITION
Configures the storage area on a disk that you set aside for caching. If you wish to have your cache span several disks, you need to configure at least one cache partition for each disk. Each partition can be independently administered. In other words, you can enable, disable, and configure a partition independently of all other partitions.
Subelements
The following table describes subelements for the PARTITION element.
Table 2-25 CACHE subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the PARTITION element.
GC
Configures the cache garbage collector that deletes files from the cache. Garbage collection can be done in either the automatic mode or the explicit mode.
Subelements
The following table describes subelements for the GC element.
Table 2-27 CACHE subelements
Element
Required
Description
zero or one
Contains a text description of this element.
Attributes
The following table describes attributes for the GC element.
The Sun Java System LDAP SchemaThis section describes the Sun Java System LDAP Schema that defines a set of rules for directory data.
You can use the dcsuffix attribute in the dbswitch.conf file if your LDAP database meets the requirements outlined in this section. For more information about the dbswitch.conf file, see dbswitch.conf.
The subtree rooted at an ISP entry (for example, o=isp) is called the convergence tree. It contains all directory data related to organizations (customers) served by an ISP.
The subtree rooted at o=internet is called the domain component tree, or dc tree. It contains a sparse DNS tree with entries for the customer domains served. These entries are links to the appropriate location in the convergence tree where the data for that domain is located.
The directory tree may be single rooted, which is recommended (for example, o=root may have o=isp and o=internet under it), or have two separate roots, one for the convergence tree and one for the dc tree.
The Convergence Tree
The top level of the convergence tree must have one organization entry for each customer (or organization), and one for the ISP itself.
Underneath each organization, there must be two organizationalUnit entries: ou=People and ou=Groups. A third, ou=Devices, can be present if device data is to be stored for the organization.
Each user entry must have a unique uid value within a given organization. The namespace under this subtree can be partitioned into various ou entries that aggregate user entries in convenient groups (for example, ou=eng, ou=corp). User uid values must still be unique within the entire People subtree.
User entries in the convergence tree are of type inetOrgPerson. The cn, sn, and uid attributes must be present. The uid attribute must be a valid e-mail name (specifically, it must be a valid local-part as defined in RFC822). It is recommended that the cn contain name initial sn. It is recommended that the RDN of the user entry be the uid value. User entries must contain the auxiliary class inetUser if they are to be considered enabled for service or valid.
User entries can also contain the auxiliary class inetSubscriber, which is used for account management purposes. If an inetUserStatus attribute is present in an entry and has a value of inactive or deleted, the entry is ignored.
Groups are located under the Groups subtree and consist of LDAP entries of type groupOfUniqueNames.
The Domain Component (dc) Tree
The dc tree contains hierarchical domain entries, each of which is a DNS name component.
Entries that represent the domain name of a customer are overlaid with the LDAP auxiliary class inetDomain. For example, the two LDAP entries dc=customer1,dc=com,o=Internet,o=root and dc=customer2,dc=com,o=Internet,o=root contain the inetDomain class, but dc=com,o=Internet,o=root does not. The latter is present only to provide structure to the tree.
Entries with an inetDomain attribute are called virtual domains. These must have the attribute inetDomainBaseDN filled with the DN of the top level organization entry where the data of this domain is stored in the convergence tree. For example, the virtual domain entry in dc=cust2,dc=com,o=Internet,o=root would contain the attribute inetDomainBaseDN with value o=Cust2,o=isp,o=root.
If an inetDomainStatus attribute is present in an entry and has a value of inactive or deleted, the entry is ignored.
VariablesSome variables are defined in server.xml for use in the obj.conf file. The following file fragment defines a docroot variable:
<PROPERTY name="accesslog" value="<Install_Root>/<Instance_Directory>/logs/access"/>
The variable is then used in the obj.conf file. For example:
Init fn="flex-init" access="$accesslog" format.access="%Ses->client.ip% - %Req->vars.auth-user% [%SYSDATE%] '%Req->reqpb.clf-request%' %Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"
Using this accesslog variable allows you to define different document roots for different virtual servers within the same virtual server class.
Format of a Variable
A variable is found in obj.conf when the following regular expression matches:
\$[A-Za-z][A-Za-z0-9_]*
This expression represents a $ followed by one or more alphanumeric characters. A delimited version ("${property}") is not supported. To get a regular $ character, use $$ to have variable substitution.
Other Important Variables
In a default installation, the following variables are used to configure various aspects of the server's operation.
General Variables
The following table lists general server.xml variables. The left column lists variables, and the right column lists descriptions of those variables.
Variable Evaluation
Variables are evaluated when generating specific objectsets. Evaluation is recursive: variable values can contain other variables.
Sample server.xml File<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2003 Sun Microsystems, Inc. All rights reserved.
Use is subject to license terms.
-->
<!DOCTYPE SERVER PUBLIC "-//Sun Microsystems Inc.//DTD Sun Java System Web Proxy Server 4.0//EN" "file:///space/proxy40/bin/proxy/dtds/sun-web-proxy-server_4_0.dtd">
<SERVER>
<PROPERTY name="accesslog" value="/space/proxy40/proxy-server1/logs/access"/>
<LS id="ls1" port="8080" servername="agneyam"/>
<MIME id="mime1" file="mime.types"/>
<ACLFILE id="acl1" file="/space/proxy40/httpacl/generated.proxy-server1.acl"/>
<USERDB id="default"/>
<FILECACHE enabled="true" maxage="30" mediumfilesizelimit="537600" mediumfilespace="10485760" smallfilesizelimit="2048" smallfilespace="1048576" transmitfile="false" maxfiles="1024" hashinitsize="0"/>
<CACHE enabled="true" cachecapacity="2000" cachedir="/space/proxy40/proxy-server1/cache">
<PARTITION partitionname="part1" partitiondir="/space/proxy40/proxy-server1/cache" maxsize="1600" minspace="5" enabled="true"/>
<GC enabled="true" gchimargin="80" gclomargin="70" gcleavefsfull="60" gcextramargin="30"/>
</CACHE>
<LOG file="/space/proxy40/proxy-server1/logs/errors" loglevel="finest"/>
</SERVER>