httpd.conf(4)

NAME | SYNOPSIS | DESCRIPTION | EXTENDED DESCRIPTION | EXAMPLES | ATTRIBUTES | SEE ALSO

NAME

httpd.conf- Server instance configuration file.

SYNOPSIS

/etc/http/instance-ID.httpd.conf

DESCRIPTION

The server instance configuration file contains directives that define the server's runtime behavior, the web sites it hosts, and the network connection end points it uses.

The directives are grouped in three major divisions. The valid directives for each division are explained in separate sections below. The major divisions are:

server { }

Defines the behavior of the server process. Includes cache settings, the userid of the server process, servlet engine settings, and server-wide defaults for the web sites hosted by the instance.

url hostname { }

Defines the identity and server resources used by a web site hosted by the server instance. There is one url {} block for each web site (or virtual host) handled by the instance, and it defines properties such as the web site's canonical host name and aliases, the location of the configuration file, and the network connections available to the web site.

port number { }

Defines the settings for a network connection or connections. The server process will attempt to bind to each port on each IP address defined in its port {} blocks. If a port is in use, the server will log an error. The server will exit if it cannot bind to at least one port. Port directives include the IP addresses on which to use the port and the timeout period.

Syntax

The following syntax rules apply to the httpd.conf file:

• The pound sign (#) is a comment character. All characters from a # to the end of a line are ignored

• White space is ignored in directive definitions.

• Some directives accept a list of values. Separate multiple values by white space. If more than one line is required to list all values, escape all but the last newline with a backslash (\) at the end of the line.

• Any value may optionally be enclosed in double quotes (").

• All directives are grouped in blocks surrounded by curly braces ({ and }). Any amount of white space, newlines, or directive definitions may appear between an opening curly brace and its matching close, including directive blocks that also use matched curly braces to contain a definition.

The overall format of the file is:

server { 
   <server directives>
}
url <hostname> {
   site_path <absolute_pathname>
   site_conf <filename>
   <web site directives>
}
[ url <hostname> { <web site directives> } ]...
port <number> {
   <port directives>
}
[ port <number> { <port directives> } ]...

There must be only one server {} block. There must be at least one url {} block, and each block-except for the default site--must have a unique hostname, a site_path directory that exists, and a site_conf file that exists in the site_path. There must be at least one port {} block, and duplicate port numbers are allowed as long as the IP address definitions are different.

See the Extended Description for the syntax of all valid directives in each division.

EXTENDED DESCRIPTION

server {} Block Directives

access_enable yes | no

Enables or disables the use of access control lists (ACLs) to control access to resources on the server. The default is yes. If ACLs are enabled, the server will look for ACLs in the file site_path/conf/access.conf for each web site hosted by the server instance.

cache_enable yes | no

Enables or disables server-side caching of documents. The default is yes. Caching can improve the performance by avoiding file system accesses for frequently requested static documents. Dynamic content, such as CGI output, is not cached.

cache_large_file_cache_size MB

Sets the size in MB of the server-side cache for large files. The large file cache caches files larger than 16 KB. The largest file size cached can be set with cache_max_file_size. The default value is 256 MB, and the maximum is only limited by virtual address space of the Sun^TM WebServer^TM process. You should rarely need to adjust this parameter.

cache_max_file_size MB

Sets the size of the largest file that will be cached in the large file cache. Documents that are larger than cache_max_file_size will never be cached. Caching works best by serving a large number of frequently requested documents. If the cache is filled with only a few very large documents, caching performance will be poor. The default cache_max_file_size is 1 (MB).

cache_small_file_cache_size MB

Sets the size of the smallest file that will be cached in the small file cache. Documents smaller than cache_small_file_cache_size will never be cached. The small file cache contains only documents smaller than 16 KB. Larger documents are stored in the large file cache or not cached at all. The default cache_small_file_cache_size is 8 (MB).

cache_verification_time seconds

Sets the number of seconds the server will wait before verifying the validity of a cached file. When Sun WebServer retrieves a file from the cache, if it has not been verified in cache_verification_time seconds, it is re-verified. If the dates are different, the file is removed from the cache and the actual file is retrieved. Cached files may become out of date if the actual file has changed. Cached files are verified by checking the date stamp of the cached file against the date stamp of the actual file. If your files only rarely change, you may want a higher value for cache_verification_time. The default is 10 (seconds).

cgi_error_log_cycle_time minutes

Sets the maximum age, in minutes, for CGI error log files for the current host. If a CGI error log is older than the number of cgi_error_log_cycle_time minutes, then a new request log file is started with an incremented sequence number. If a log file contains no entries, then no new log file will be generated regardless of how much time has passed. Default is 1440 minutes (1 day).

cgi_error_log_enable yes | no

Enables or disables CGI script error logging. The default is no.

cgi_error_log_max_files integer

Sets the maximum number of CGI error log files that Sun WebServer will keep for this host. Log files end with a sequence number suffix which is incremented when a new log file is created. If the sequence goes beyond cgi_error_log_max_files, it is reset to 1 and the first CGI error log file is overwritten. This prevents the number of log files from growing without limit. Set cgi_error_log_max_files to "-1" to have no limit on the number of log files. Default is 7 files.

cgi_error_log_max_file_size bytes

Sets the maximum file size, in bytes, for CGI error log files for the current host. If a CGI error log exceeds cgi_error_log_max_file_size, a new log file is started with an incremented sequence number. Default is 1048576 bytes (1 MB).

cgi_error_log_prefix prefix

Sets the directory and log file name prefix for cgi script error logs for a given host. The string must have an absolute path name followed by the prefix that will be used for this host's log files. Separate virtual hosts must have different prefix names so that there is no conflict in writing to the logs. Each of a hosts log files will have a name in the form:

<absolute pathname>/prefix.<sequence>

For example, /var/http/logs/http.2. Sequence is incremented and a new file created whenever cgi_error_log_cycle_time or egi_error_log_max_file_size is reached. If a log file contains no entries, then no new log file will be generated regardless of how much time has passed. Default is "var/http/logs/http".

comment "description"

Simply a comment string to describe the current configuration file.

default_file file [[file...]]

Lists in order of preference the name of the file Sun WebServer will look for in a directory when a URL request does not name a specific file. For example, if the URL request is for http://hostname/, Sun WebServer will look at the top directory of host name's doc_root for a file named default_file.

If default_file does not appear in the configuration file, then "index.html" is used. If default_file is " ", then no default file is used. If multiple files are specified, then the files are used in the specified order.

If no file matching the values for default_file is found, the directory contents will be listed, subject to the value of directory_listing.

The built in server-wide default is "index.html".

directory_listing fancy | simple | off

Specifies how the contents of directories will be listed if no file matching default_file is found in the directory. directory_listing is valid in server {} blocks as server-wide defaults or in url {} blocks for per-host settings.

fancy

Displays directory contents with each name as a hyperlink to the file, icons matching each file's type, and file size and date information. The icons used and the association of icons to file suffixes is configurable.

simple

Displays only each file name as a hyperlink to the file itself.

off

Disables displaying directory contents; an HTTP "404 Not Found" error is returned to the client instead.

The built in server-wide default is "fancy".

error_document http_error_code_url

Allows customized error messages to be returned to the client. Any valid URL, including CGI scripts, may be returned, so you have flexibility in what information you want to give clients when an error occurs. When an HTTP error code is returned, Sun WebServer will return an HTTP "302: Document Moved" header with a Location: header indicating the file to which the error has been remapped. Most clients will automatically fetch the URL named by the Location: header. You can redirect the following HTTP error codes:

• 400 - Bad Request (Remapped by default host only)

• 403 - Forbidden

• 404 - Not Found

• 412 - Precondition Failed

• 500 - Server Error

• 501 - Not Implemented

• 503 - Service Unavailable

The destination URL can be relative to the current or default host if it begins with a "/". Otherwise, an absolute URL must be specified. The following examples show a relative and absolute URL, respectively:

• error_document "503"

• "/cgi-bin/error.pl?503"

• error_document "500"

• "http://www2.A.com/mirror/"

---

Note -

The path to which you remap 404 errors must be available in the document root. You can not redirect 404 errors to aliased directories. error_document is valid in server {} blocks as server-wide defaults or in url {} blocks for per-host settings.

---

icon_add alt_text bitmap_URI file_type[[file_type]]...

Allows association of a file extension with an icon file. The icon will be used to represent all files with the extension in fancy directory listings. icon_add can also change a default association or assign icons to file types not covered in the default set; for example, you may want to use your own icons to represent basic types. In addition to file suffixes, you can customize the icon used for "parent directory" (../) and "subdirectory" by specifying "UP" or "DIR" as the alt_text.

alt_text

Specifies a string that will be used instead of an icon in text-only browsers. For example, "GIF".

bitmap_URI

Specifies a URI path relative to the default host (in the server {} block) or the host named by the current url {} block. For example, "/icons/binary.xbm".

file_suffix(es) | content_type(s)

Specifies a string of one or more file extensions or content type definitions that will use the icon in "fancy" directory listings. For example, "jpg jpeg JPG image/jpeg" assigns the icon to all files ending in .jpg, .jpeg, and .JPG or files with a MIME type of image/jpeg.

In addition to file suffixes, you can customize the icon used for "parent directory" (../) and "subdirectory" by specifying "UP" or "DIR" as the alt text. icon_add is valid in server {} blocks as server-wide defaults or in url {} blocks for per-host settings.

icon_default bitmap_URI

Sets the icon used for files with extensions that do not have a defined icon type. The path to the bitmap file must begin with a "/", and it is relative to the default host or the host defined by the current url {} block. icon_default is valid in server {} blocks as server-wide defaults or in url {} blocks for per-host settings.

lwp_threads_count integer

Sets the total number of lightweight process (LWPs) threads in the kernel that Sun WebServer will attempt to use to map to user threads in its thread pool. By default, Sun WebServer uses 1 LWP per user thread (lwp_threads_count will equal threads_n_active).

Increasing this number may increase the actual thread concurrency of Sun WebServer, and it will also increase the share of system resources used by the httpd process.

mime_file relative_path

Contains the default MIME types definitions used for the server host. Default is /etc/http/mime.types. The order in which Sun WebServer will attempt to match a file with a MIME type is as follows:

1. Check any host-specific mime_add definitions.

2. Check any mime_add and mime_file definitions in the server {} block.

3. If none of the above produces a MIME type for the file, the mime_default_type is used. Entries in the mime_file have the form:

   <type>/<subtype><file suffix(es)>

   For example: text/html html htm. The default server-wide mime_file is /etc/http/mime.types.

---

Note -

If mime_file and mime_add directives appear in the server block, later definitions will replace earlier definitions. For example, if a mime_add definition appears after the mime_file directive, it will replace a matching definition in the MIME types file. mime_file is valid in server{} blocks as server-wide defaults or in url {} blocks for per-host settings.

---

mime_default_type type/subtype

Sets the MIME type that will be used for files whose extension does not match any other MIME type. The default is "text/html". mime_default_type is valid in server{} blocks as server-wide defaults or in url {} blocks for per-host settings.

server_admin email_address

Specifies the email address of the Sun WebServer administrator.

server_classpath path[[:path]]...

Specifies the Java^TM classpath where the JDK, JSDK, and classes for the servlet engine are located.

---

Note -

This is not the path for servlets to be loaded.

---

server_root absolute_path

Specifies the path in which the server-wide scripts, icons, and base for sites hosted by the instance are stored.

server_user username

Sets the user name Sun WebServer will use after start up. The string must be a valid user name on the system. After httpd is started by root, it will change to the server_user user name. The default server_user is root. The server_user must be able to read and write the configuration file, any ACL files, read files in the doc_root directories, and be able to read and write files in any log file directories. You can set the server_user so the server does not run with root permissions. By running as a different user, there are fewer security risks because the server will be unable to change or serve to clients sensitive files owned by root. You may want to create a user only to run Sun WebServer, and make sure that this user owns or has access to all of the necessary files and directories.

servlet_engine { parameters }

Specifies parameters of the servlet engine:

chaining_enable yes | no

Enables or disables servlet chaining. This enables the servlet engine to run a sequence of servlets in a specified order to fulfill one single servlet request. Host administrators can specify a chain of servlets to be executed sequentially. Default is "no".

dynamic_linking_enable all | local | remote | none

Allows the specified servlets access to dynamic libraries. Default is "none".

file_access_enable all | local | remote | none relative_path

Allows specified servlets to have access to file resources, for example, read/write a file on local disk. Default is "local".

network_access_enable all | local | remote | none

Allows specified servlets to have access to network resources, for example, open a socket. Default is "local".

properties_file relative_path

Path to "servlets.properties". All loadable servlets are specified in this file. Each servlet engine instance can have a list of preloaded servlets that it wishes to load and initialize as soon as the server starts. This list is specified in a servlet properties file. Path can be either absolute or relative to site_path.

reload_enable yes | no

Allows or disallows the servlets to reload. If the servlet classfile changes, a servlet instance (reflecting the changes) can be reloaded. Reloading can be performed by either the server or the host administrator, depending on whether the hosts are sharing a servlet engine instance. Servlets do not reload automatically and will reload only when explicitly requested. The default is "no".

remote_enable yes | no

Enables or disables remote servlets. Enabling remote servlets allows the servlets from remote sites to be loaded by the server. The default is "yes".

se_log_enable yes | no

Enables or disables the servlet error logging. The default is "no".

se_log_cycle_time minutes

Sets the maximum age, in minutes, for servlet error log files for the current host. If a servlet error log is older than the number of se_log_cycle_time minutes, then a new servlet error log file is started with an incremented sequence number. If a log file contains no entries, then no new log file will be generated regardless of how much time has passed. Default is 1440 minutes (1 day).

se_log_max_files integer

Sets the maximum number of servlet error log files that Sun WebServer will keep for this host. Log files end with a sequence number suffix which is incremented when a new log file is created. If the sequence goes beyond se_log_max_files, it is reset to 1 and the first servlet error log file is overwritten. This prevents the number of log files from growing without limit. Set se_log_max_files to "-1" to have no limit on the number of log files. Default is 7 files.

se_log_max_file_size bytes

Sets the maximum file size, in bytes, for servlet error log files for the current host. If a servlet error log exceeds se_log_max_size, a new log file is started with an incremented sequence number. Default is 1048576 bytes (1 MB).

se_log_prefix absolute_path/prefix

Sets the directory and log file name prefix for servlet error logs for a given host. The string must have an absolute path name followed by the prefix that will be used for this host's servlet log files. Separate virtual hosts must have different prefix names so that there is no conflict in writing to the logs. Each host's servlet log files will have a name in the form:

<absolute pathname>/prefix.<sequence>

For example, site_path/logs/se_logs.2. Sequence is incremented and a new file created whenever se_log_cycle_time or se_log_max_file_size is reached. If a log file contains no entries, then no new log file will be generated regardless of how much time has passed. Default is"site_path/logs/se_logs".

security_access_enable all | local | remote | none absolute_path/prefix

Allows the specified servlets to have access to security resources, for example, classLoaders. Default is "local".

system_access_enable all | local | remote | none

Allows or disallows the specified servlets to have access to system resources, for example, call System.Exec(). Default is "local".

servlets_path path

Specifies the absolute path to local directories for jar files for all local servlets. This is a colon-separated list.

server_servlets_enable yes | no

Allows or disallows servlets to run in this server process. This option controls whether to start the JVM for this process. The default is "no".

site_restrictions { directives }

Enables access to the following:

cgi_superuser yes | no

Allows or disallows cgi_user setting of any web site to be root. Default is "no".

cgi_user_unique yes | no

Determines whether the cgi_user setting of any web site must be unique throughout the server. Default is "yes".

cgi_dns_enable yes | no

Enables or disables the REMOTE_HOST CGI environment variable to be set and to be available to CGI scripts. REMOTE_HOST requires a DNS lookup of the IP address (REMOTE_ADDR) of the resource making the CGI request. Since DNS lookups can be resource consuming, allowing such DNS lookups can slow performance, especially on a server that uses extensive CGI. The default is "no".

se_share yes | no

Enables all web sites to share the servlet engine defined in the server block if set to "yes". If set to "no", there is no sharing and each web site can have its own servlet engine. This is a server-wide setting. The default is "no".

symlink_follow yes | no

Follows or ignores symbolic links in the file system. Ignoring symbolic links may cause a performance loss as the file name and each directory in the path of a requested resource must be checked to make sure there are no symbolic links. Following symbolic links may be a security risk because a symbolic link can potentially point to a file that is outside of the doc_root. A symbolic link to a sensitive file (such as /etc/passwd) can only be made by someone with write access to the file, so the security risk is often small and easily managed by controlling who has access to the document root. symlink_follow is valid in server {} blocks as server-wide defaults or in url {} blocks for per-host settings. Default is "yes".

threads_n_active integer

Specifies the maximum number of user threads Sun WebServer will have available in its thread pool. The number of threads will not grow beyond this number. Sun WebServer uses one thread per connection, releasing the thread to the thread pool when the request has completed. For keepalive connections, the thread is released to the thread pool after a request has completed, and a new thread is used if there is a new request on the connection. The number of threads sets an upper limit on the number of simultaneous connections Sun WebServer can handle. The default value is 128 threads.

user_doc_source source

Specifies the source of user information for user document directories if user_doc_enable is "yes." In most cases, the only valid value is UNIXSYS, and users are defined through the operating system (for example, in /etc/passwd or NIS).

In Solaris for ISPs, if virtual FTP servers have been defined in Sun Directory Services, you may set this to ISP. User information will be taken from the directory server, and the value of a user's ispContentDirectory will be used.

version version_string

Describes the current version of Sun WebServer.

url {} Block Directives

alias hostname

Defines other names for the specified virtual host.

conn_end_points [[IP_address | *]]:port [[[[IP_address | *]]:port]]...

Determines the IP address and port numbers on which requests to this web site are accepted. The syntax of this directive is

[<ip_address>]:port number

If the ip_address refers to the set of all IP addresses for this web site, then for HTTP 1.1 virtual hosts, leaving the ip_address field blank means that it is available on all IP addresses.

This directive may not appear in the url {} block for the default virtual host. In consequence, the default host will receive all requests to unknown hosts and all HTTP 1.0 requests not addressed to any host that arrive on any port. The server rejects with error 400 HTTP 1.1 requests not addressed to any host.

owner_group groupname

Defines the UNIX group who owns the web site's content files.

owner_user username

Defines the UNIX user and group who own the web site's content files.

site_config path

Specifies the relative path configuration file for the web site.

site_enable yes | no

Determines whether the site is currently enabled and accepting requests. site_enable is not an initialized setting. A site is enabled once it has been configured successfully. After successful configuration, use hthost to enable or disable the site.

site_path directory_path

Specifies the absolute path location of the web site.

port {} Block Directives

ip_address nnn.nnn.nnn.nnn

Indicates the IP address on the server that can receive requests on the current port. Use this if you do not wish to support all IP addresses on a port. You need to create a separate port {} block with the same port number for each specific ip_address you want to support. Use separate port {} blocks with unique ip_address settings to support IP-based virtual hosting. If this parameter is omitted, all IP addresses on the server will be supported on the port. The default is all IP addresses.

keepalive_enable yes | no

Allows or disables HTTP 1.0 keepalive connections on the current port. HTTP 1.1 connections always use keepalive, but HTTP 1.0 browsers can only establish a keepalive connection with Sun WebServer by sending a Connection: keepalive HTTP header (if keepalive_enable is set). Keepalive may improve performance since the connection is not destroyed and reestablished for each HTTP request. The default is "yes".

request_timeout seconds

Sets the maximum time, in seconds, that Sun WebServer will wait to fill an individual client request on the current port. The default is 180 seconds (three minutes).

ssl_client_cert_required yes | no

Determines whether the server will demand a certificate signed by a CA known to the server when a client connects to the SSL port. The default is "no".

ssl_enabled yes | no

Enables or disables the Secure Sockets Layer (SSL). SSL encrypts and authenticates messages sent between a browser and Sun WebServer. Encryption using public key cryptography ensures the privacy of the messages sent between the client and Sun WebServer. Port 443 is the default SSL port and is recommended for easiest use by clients (no port will need to be specified in the https URL). The default is "no".

---

Note -

To run SSL, you will need to set up a local root Certificate Authority (CA) with a Distinguished Name record, and generate a private/public key pair for the local root CA. The local root CA will be able to generate credentials and key pairs for every SSL-enabled host within your organization, whether it is a single host or a machine running Sun WebServer with hundreds of virtual hosts. The security tools use the Federated Naming System (FNS) to manage the naming context for users and hosts with certificates.

---

ssl_ciphers cipher_string(s)

Sets the cipher parameters used for SSL encryption. It may be one of the following:

SSL_RSA_EXPORT_WITH_RC4_40_MD5

For 40-bit exportable ciphers. This is the default setting.

SSL_RSA_WITH_RC4_128_MD5

For 128-bit, North America only cipher (this requires separate SSL packages not available in the downloadable version of Sun WebServer).

EXAMPLES

---

Example 1




A sample configuration file:

# Automatically generated.
#
#       SWS HTTP server configuration file
#
# file version number
version "SWS2.0"

server {
        comment                  "Sample Configuration"
        server_root              "/var/http/sample/"
        server_user              "root"
        cache_enable             "yes"
        cache_large_file_cache_size 256
        cache_max_file_size      1
        cache_small_file_cache_size 8
        cache_verification_time  10
        cgi_error_log_cycle_time 1440
        cgi_error_log_enable     "no"
        cgi_error_log_max_files  7
        cgi_error_log_max_file_size 1048576
        cgi_error_log_prefix     "error_log"
        lwp_threads_count        1
        threads_n_active         128
        access_enable            "yes"
        symlink_follow           "yes"
        user_doc_source          "ISP"
        directory_listing        "fancy"
        default_file             index.html
        mime_default_type        "text/html"
        mime_file                "/etc/http/mime.types"
        icon_default             "/sws-icons/unknown.xbm"
        
        site_restrictions {
                se_share                 "yes"
                cgi_superuser            "no"
                cgi_user_unique          "no"
                cgi_dns_enable           "no"
        }
        server_classpath         "/usr/lib/http/classes.zip:/usr/jsdk/lib/classes.zip:/usr/java/lib/classes.zip"
        server_servlets_enable   "yes"
}

url {
        site_enable              "yes"
        site_path                "/var/http/sample/websites/default_sites"
        site_config              "conf/default_sites.site.conf"
        owner_user               "admin3"
}

port 80 {
        ip_address           129.146.146.146
        keepalive_enable         "yes"
        request_timeout          180
}

---

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWhttp
Interface Stability	Evolving

SEE ALSO

htserver(1m), hthost(1m), httpd.site.conf(4)

Sun WebServer 2.0  Last Revised 17 July 1998

NAME | SYNOPSIS | DESCRIPTION | EXTENDED DESCRIPTION | EXAMPLES | ATTRIBUTES | SEE ALSO