WEBMASTER IN A NUTSHELL Stephen Spainhour & Robert Eckstein A Desktop Quick Reference 3 rd Edition Third Edition WEBMASTER IN A NUTSHELL Stephen Spainhour and Robert Eckstein Beijing • Cambridge • Farnham • Köln • Paris • Sebastopol • Taipei • Tokyo 453 This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc. All rights reserved. Chapter 18Apache 18 Apache Configuration The Apache HTTP Server is the most widely used web server on the Internet. The Apache server was developed from an early version of the original NCSA server with the intent of providing further improvement while maintaining compati- bility. Since then, all development efforts on the NCSA server have ceased. Apache has since earned the title of reigning king among web servers, and it isn’t hard to see why: the base distribution is fast, free, and full-featured. It runs on many different platforms and has a multitude of third-party modules available to expand its functionality. You can pick up a copy of the Apache server and its documentation from the Apache home page: http://www.apache.org. This chapter covers Version 2.0 of the Apache server. Most of the configuration and module functionality are similar to the last major release, 1.3, which is still in wide use. Major differences between the versions will be noted. Understanding Apache The Apache distribution consists of the source for the core binary, httpd, the stan- dard set of modules, and numerous additional header and configuration files. You can compile the server for your particular architecture and preferences using the config-make-make install routing common to building open source software. The latest version of gcc or another up-to-date ANSI C compiler is required to compile and build Apache. However, you may not have to compile Apache from source. Most Linux and Mac OS X distributions have Apache already built-in. Furthermore, binaries are avail- able for most popular platforms. Refer to www.apache.org for details. By itself, httpd doesn’t do more than listen for requests and deliver files as is. Apache is designed to load special modules to implement additional functionality. These modules define much of the behavior of the Apache server. A set of standard 454 | Chapter 18: Apache Configuration This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc. All rights reserved. modules is distributed with the server, including a set of core modules that is auto- matically compiled into the server binary. Apache will call on modules as needed to perform a dedicated task, such as user authentication or database queries. Loading Modules Modules must be compiled first to be used by the server, and can be loaded in two ways: statically or dynamically. Modules can be statically built directly into the server binary at compile time: ./configure --enable-module ./configure --disable-base_module ./configure --enable-modules=module_list Alternatively, you can compile modules as DSO’s (Dynamically Shared Objects) and load them as needed at run-time (when the server is started or restarted) by identifying them with the LoadModule directive in the configuration file. To compile shared modules at compile time, use: ./configure --enable-MODULE=shared DSO modules may also be compiled with apxs (Apache Extension Tool) at any time outside of the Apache source tree. See the Apache documentation for full details on apxs. Server Configuration At startup, Apache reads the main server configuration file httpd.conf. You can control the behavior of the server and its modules by inserting or modifying the directives within this file. Additional configuration can occur on a directory- specific level using .htaccess files. These are configuration files like httpd.conf, but the directives they contain apply only to the directory where they reside. This allows for delegation of control over separate content areas of a single server, and may simplify server management. The Apache server uses one other configuration file, mime.types, to determine what MIME types should be associated with what file suffixes (see Chapter 17). The configuration files contain directives, which are one-line commands that tell the server what to do. In addition to the directives themselves, the configuration files may contain any number of blank lines or comment lines beginning with a hash mark ( # ). Although directive names are not case-sensitive, we use the case conventions in the default files. Example copies of each of these files are included with the server software distribution, which you can refer to for more information. The first things Apache needs from the configuration file are basics like the listening port, server name, the default locations for content, logs, and other important files, and what modules to load. After that, the wider server function- ality is configured. This includes access control, virtual hosts, special resource handling, and module-specific directives. Understanding Apache | 455 Apache Configuration This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc. All rights reserved. Here are some basic directives you might find in the httpd.conf configuration file: ServerType standalone Port 80 ServerAdmin webmaster@oreilly.com ServerName webnuts.oreilly.com User nobody Group nobody Each directive here specifies a property of the server’s configuration and binds it to a default setting or value. Since these directives exist on their own in the config- uration file, their context is that of the whole server. Many directives will appear in special subsections that limit their scope. Directives that define subsections are bracketed, XML-like elements. For example: <Directory /docs> Deny From All </Directory> This configuration section sets a directive for requests to a single directory /docs. Many configuration sections apply to locations of file on the server, such as <Files> , <Location> , and <Directory> . Other configuration sections define virtual servers ( <VirtualHost> ) or contain directives specific to a module ( <IfModule> ) All server configuration can occur in the httpd.conf file, but you may want to allow special configuration of only certain parts of your server—you could let a user configure some aspects of how documents in her directory are served. By default, Apache looks for .htaccess files in every directory it serves a file from. .htaccess may contain any configuration directives allowed by the server configuration file with the AllowOverride directive. For example, if httpd.conf contained the line: AllowOverride AuthConfig most of the directives from the user authorization modules ( Auth* ) could be used in an .htaccess file to limit access to the files in that directory. This is exactly equivalent to using the same directives within a specified <Directory> section in httpd.conf. Since .htaccess files affect the directory they are in and any subdirectories, they have a cascading affect on configuration. A directive in a lower-level .htaccess requires an AllowOverride from a parent-level .htaccess to work. This places increased load on the server, which must search for .htaccess files and parse them for every request in the current and parent-level directories. If you want to completely ignore .htaccess files, use AllowOverride None in httpd.conf. Handling Requests On Unix systems, the Apache daemon httpd always starts itself as a system supe- ruser (root). This is often done at startup through entries in the system initialization files. On Windows, the Apache service is called apache and runs with administrator privileges. 456 | Chapter 18: Apache Configuration This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc. All rights reserved. Once started, Apache’s job is to listen for requests on any address and port to which it has been configured. When handling a request from a specific client, Apache spawns a separate process to handle the connection. This spawned process, however, doesn’t run as the superuser; for security reasons, it instead runs as a restricted user that serves files to the client. Apache normally has five such processes waiting for connections; hence, after startup, you will see one process (httpd) running as root and five processes owned by the Apache user ID, which stand to service requests. You can reconfigure that number, as well as the minimum and maximum number of service processes allowed with the StartServers , MinSpareServers , and MaxSpareServers directives. Each process handles specific HTTP requests for the client, such as GET or POST, which affect content on the server. All resources available to visiting browsers (HTML documents, images, etc.) reside by default under a single root directory defined by the DocumentRoot direc- tive. This defines the base directory that is prepended to a URL path to locate a file on the server. Most URL mapping is as simple as locating a file under the document root, but more complex mapping can be defined through aliasing, redi- rection, and URL rewriting using the mod_alias and mod_rewrite modules. Access Control Webmasters often find the need to restrict some or all of the data on their servers to authorized users. Access can be controlled by requiring username and pass- word information or by restricting the originating IP address of the client request. The mod_access and mod_auth core modules provide basic access control for Apache. Access control is usually confined to specific directories of the document tree. You can place authorization directives in httpd.conf within <Directory> sections, or within .htaccess files in the restricted directory itself (using AllowOverride AuthConfig ). This example shows the directives used to configure username and password access to a specific directory: <Directory /projects> Options All AuthType Basic AuthName "Editorial Group" AuthUserFile /usr/local/etc/httpd.conf/.htpasswd AuthGroupFile /usr/local/etc/httpd.conf/.htgroup require group editors </Directory> The AuthType directive specifies the type of authentication used. “Basic” authenti- cation describes the simple authorization scheme used by Apache where user password files are created with the htpasswd program. AuthName specifies the authorization “Realm”. The realm can describe many different server locations so that an authorized user does not have to re-supply his password information as he Understanding Apache | 457 Apache Configuration This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc. All rights reserved. navigates. AuthUserFile provides the user/password file location, and AuthGroupFile provides the group file location. require sets the restriction to only members of the group “editors”. The following configuration section limits access to a directory to requests from a specific domain: <Directory /projects/golf> order deny,allow deny from all allow from .golf.org </Directory> Password and Group Files A password file is needed for user and group-level authentication. The location and name of the password file are specified with the AuthUserName directive. The easiest and most common way to create a password file or add passwords is to use the htpasswd program that is distributed with the server. If a password file already exists for a location, you can type: htpasswd pathname username The program then asks you to type the password you wish for the given username twice, and the username and encrypted password are stored in the new file. If a password file does not exist yet, you can create one by typing the same command with the -c option (e.g., htpasswd -c pathname username ). But be careful, since the -c option will create a new file without checking if one already exists, thereby overwriting any existing passwords. Password files created with .htpasswd are similar to Unix password files. Keep in mind, however, that there is no correspondence between valid users and pass- words on a Unix server, and users and passwords on an Apache web server. You do not need an account on the Unix server to access the web server. You can bundle several users into a single named group by creating a group file. The location and name of the group file are specified with the AuthGroupFile directive. Each line of a group file specifies the group name, followed by a colon, followed by a list of valid usernames that belong to the group: groupname: username1 username2 username3 . Each user in a group needs to be entered into the Apache password file. When a group authentication is required, the server accepts any valid username/password from the group. The .htpasswd user authentication scheme is known as the basic authentication method for HTTP servers. Apache allows other types of authentication methods, which are configured with a similar set of directives. 458 | Chapter 18: Apache Configuration This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc. All rights reserved. Virtual Hosting Apache also has the ability to perform virtual hosting. This allows a single httpd process to serve multiple IP addresses or hostnames. Virtual hosting seems like a complicated procedure; however, it really isn’t as bad as it seems. In each configu- ration file, you can structure directives that apply only to virtual hosts. For example, you can specify separate DocumentRoot directives for each virtual machine, such that someone connecting to www.oreilly.com is served one set of documents, while another client connecting to www.onlamp.com receives another, even though the content for each of these sites is served by the same server on the same machine. To create a virtual server, simply enclose httpd.conf directives related to the server in a <VirtualHost> directive. Here is an example httpd.conf configuration that will set up two virtual servers: ServerName www.oreilly.com AccessConfig /dev/null ResourceConfig /dev/null <VirtualHost www.oreilly.com> ServerAdmin webmaster@oreilly.com DocumentRoot /usr/local/www/virtual/htdocs/oreilly ServerName www.oreilly.com ErrorLog /usr/local/www/virtual/htdocs/oreilly/error_log TransferLog /usr/local/www/virtual/htdocs/oreilly/transfer_log </VirtualHost> <VirtualHost www.onlamp.com> ServerAdmin webmaster@onlamp.com DocumentRoot /usr/local/www/virtual/htdocs/onlamp ServerName www.onlamp.com ErrorLog /usr/local/www/virtual/htdocs/onlamp/error_log TransferLog /usr/local/www/virtual/htdocs/onlamp/transfer_log </VirtualHost> Log Files Apache creates two log files by default: the error log and the access log. The server’s error log records any errors the server encounters during execution. The access log records all client requests made to the server. You can set the locations of these files with the ErrorLog and CustomLog directives. Access logs are highly configurable. The LogFormat directive allows you to specify which data is recorded for each server transaction. For example, the following directive: LogFormat "%h %l %u %t \"%r\" %>s %b" common configures the access log to record information in the Common Log Format, which includes such data as the client IP, user ID, time of request, the request command, and the server’s response. Basic Server Configuration: Core Directives | 459 Apache Configuration This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc. All rights reserved. AccessFileName Basic Server Configuration: Core Directives The following section contains core directives that are independent of modules and can be used in the Apache server at all times. With each directive, we indi- cate any version constraints that are required, as well as the context the directive should appear in. Contexts include: server config The directive is allowed in the httpd.conf or srm.conf configuration files. <VirtualHost> The directive can appear inside a <VirtualHost> subsection, stating that the directive applies to a virtual server. <Directory> The directive can appear inside a <Directory> subsection, stating that the directive applies to a specific directory tree on the server. .htaccess The directive can appear inside the per-directory .htaccess access control files. Directives pertaining to specific Apache modules are covered in Chapter 19. AcceptPathInfo AcceptPathInfo on|off|default Determines if extra information following a valid URL pathname is accepted by the server or not. An off value means that a request is rejected if the pathname doesn’t match exactly a server resource. on means that the server ignores the extra path information and returns the resource that will match a valid part of the path. The default setting allows the default handler to determine action. If the resource is a CGI script, extra path info may be allowed, but not if the request is for a file. AccessConfig AccessConfig filename [server config or within < VirtualHost > ] Specifies the location of the access configuration file, either as an absolute path (with a beginning slash) or as a relative path from the ServerRoot directory. For example: AccessConfig conf/access.conf AccessFileName AccessFileName filename filename . [server config or within <VirtualHost>] Specifies the names of one or more per-directory access control files. The default is: AccessFileName .htaccess 460 | Chapter 18: Apache Configuration This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc. All rights reserved. AddDefaultCharSet AddDefaultCharSet AddDefaultCharSet on|off|charset Specifies whether the server will add a default CharSet header to outgoing HTTP headers that do not have a Content Type set. If set to on the default Apache charset will be used. Otherwise, you can provide the character set string you wish. AllowOverride AllowOverride options . [Within <Directory> ] Controls the extent to which local per-directory .htaccess files can override the defaults defined by access control files in higher direc- tories. The directive takes one or more options, which can be: None Access control files are unrecognized in this directory. All Access control files are unrestricted in this directory. Options Allow use of the Options and XBitHack directives. Indexes Allow use of directory indexing directives ( FancyIndexing , AddIcon , and AddDescription , etc.). FileInfo Allow use of the directive relating to document type: ( AddType , AddEncoding , AddLanguage , etc.). AuthConfig Allow use of these directives: require , AuthName , AuthType , AuthUserFile , AuthGroupFile , or any other Auth* directives. Limit Allow use of the allow , deny , and order directives. If omitted, the default is: AllowOverride All AuthName AuthName name [Within <Directory> or .htaccess] Sets the name of the username/password authorization realm for this directory. The value is a short name describing this authoriza- tion realm; it can contain spaces. AuthType AuthType type [Within <Directory> or .htaccess] Sets the type of authorization used in this directory. Basic authoriza- tion is the most commonly used method. If used, this directive should be followed by AuthName , require , AuthGroupFile , and AuthUserFile directives, which better describe the authorization realm. [...]... is executed if Apache is compiled with the mod_cgi module Note that you can place an exclamation mark in front of the module name to include such directives if a module is not included in the Apache server build Include Include filename [server config, within , or ] Tells the server to include a specified file as part of its configuration 464 | Chapter 18: Apache Configuration. .. crit Reports critical conditions from server execution error Reports error conditions in Apache execution warn Basic Server Configuration: Core Directives | This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc All rights reserved 467 Apache Configuration Reports warnings in Apache execution MaxClients notice Reports common, noteworthy conditions info Reports informational... when the information is requested There are three options, listed with the appropriate formats: ProductOnly (Prod) Server: Apache Major Server: Apache/ 2 Minor Server: Apache/ 2.0 Minimal (Min) Server: Apache/ 2.0.41 OS Server: Apache/ 2.0.41 (Unix) Full Server: Apache/ 2.0.41 (Unix) PHP/4.2.2 MyMod/1.2 ServerType ServerType standalone|inetd [server config] Specifies whether your server is run standalone... The default is: ScoreBoardFile logs /apache_ status SendBufferSize SendBufferSize bytes [server config] Resets the TCP buffer size, typically over the OS default ServerAdmin ServerAdmin email_address Basic Server Configuration: Core Directives | This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc All rights reserved 471 Apache Configuration [server config, or within... or htaccess] Forces all files in its scope to be served as the specified MIME type Group Group groupname Basic Server Configuration: Core Directives | This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc All rights reserved 463 Apache Configuration [server config or within ] Specifies the group you want the server to process requests as Either... The server follows symbolic links only if the target file/directory is owned by the same user ID as the link All Basic Server Configuration: Core Directives | This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc All rights reserved 469 Apache Configuration All features are enabled in this directory PidFile The Options directive can be used in both the global access.conf... apply It cannot be used in a per-directory htaccess file The start tag has this format: Basic Server Configuration: Core Directives | This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc All rights reserved 461 Apache Configuration where regex is a regular expression that designates one or more directories the enclosed directives apply to... Chapter 18: Apache Configuration This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc All rights reserved StartServers ServerTokens ServerTokens Minimal|OS|Full [server config] Specifies which type of header field is returned to clients when the information is requested There are three options, listed with the appropriate formats: ProductOnly (Prod) Server: Apache. .. directives are the usual inhabitants of the Limit sectioning directive This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc All rights reserved 465 Apache Configuration Basic Server Configuration: Core Directives | The reverse functionality of the directive restricts any methods... filter or filters to process server responses before they are sent to the client StartServers StartServers number Basic Server Configuration: Core Directives | This is the Title of the Book, eMatter Edition Copyright © 2002 O’Reilly & Associates, Inc All rights reserved 473 Apache Configuration [server config] Specifies the initial number of slave processes at server startup The default is 5 This directive . reserved. Chapter 1 8Apache 18 Apache Configuration The Apache HTTP Server is the most widely used web server on the Internet. The Apache server was developed. a copy of the Apache server and its documentation from the Apache home page: http://www .apache. org. This chapter covers Version 2.0 of the Apache server.