This document provides an overview and summary of Apache 2.2 configuration including: 1) Apache release statuses and where development is focused; 2) Common configuration directives like Listen, DocumentRoot, and VirtualHosts; 3) Tips for modularizing configuration using Include directives and separating into files.

1. Understanding Apache 2.2 Configuration Brad Nicholes Senior Software Engineer, Novell Inc. Member, Apache Software Foundation [email_address]

2. Agenda Apache 2.2 Status Multi-Processing Modules Common Configuration Directives Tips and Tricks Authentication & Authorization What’s new in Apache 2.3

3. Apache Web Server Status Shipping: Apache 1.3.37 – Maintenance mode, no new development Apache 2.0.59 – Maintenance mode, no new development Apache 2.2.4 – Current release Development: Apache 2.2.5-dev – Stable Apache 2.3.x-dev – Unstable, all new development happens here first

4. Apache 2.2 for NetWare Apache 1.3 ported to NetWare in 2000 All current versions of Apache including 2.2.x and 2.3.x are fully functional on the NetWare platform Apache 2.0 became generally available on NetWare 6.5 New releases are available from the Apache HTTP project download site: http://www.apache.org/dist/httpd/binaries / Installed by default on SYS:/Apache2

5. Apache 2.2 on SuSE Linux File Locations Modules - /usr/lib/apache2 Configuration - /etc/apache2 Logs - /var/log/apache2 Cgi-bin - /srv/www/cgi-bin DocumentRoot - /srv/www/htdocs Binary - /usr/sbin/httpd2 (symlink to actual binary) /usr/sbin/httpd2-worker /usr/sbin/httpd2-prefork Other support binaries - /usr/sbin Startup script – /usr/sbin/rcapache2 Symlink to /etc/init.d/apache2

6. Multi-Processing Modules Accommodate a wide variety of operating environments on different platforms Responsible for: Binding to network ports Accepting requests Dispatching worker threads to handle requests Allows customization for particular sites Scalability in a threaded environment – Worker MPM Compatibility with older modules – Prefork MPM Platform custom – NetWare MPM, WinNT MPM

7. Worker MPM Combines multi-process and multi-threaded models Variable number of processes (parents) Fixed number of threads Each child process handles many concurrent connections Stability of multiple processes Performance of multiple threads Reduces the memory footprint

8. Multi-Processing Modules Worker MPM - Multi-Processing Module implementing a hybrid multi-threaded / multi-process web server StartServers - Number of child server processes created at startup MinSpareThreads - Minimum number of idle threads allowed before additional worker threads are created MaxSpareThreads - Maximum number of idle threads allowed before excess worker threads are destroyed MaxClients - Maximum number of worker threads allowed MaxMemFree - Maximum amount of memory that the main allocator is allowed to hold without calling free() ThreadsPerChild - Number of threads created by each child process http://httpd.apache.org/docs/2.2/mod/worker.html

9. Prefork MPM Stable but slower (based on documentation) One parent (master server) many children (workers) Each child server is a process itself Each child handles one connection at a time Uses more memory Similar to the NetWare MPM but using processes instead of threads

10. Multi-Processing Modules Prefork MPM - Implements a non-threaded, pre-forking web server StartServers - Number of child server processes created at startup MinSpareServers - Minimum number of idle child server processes MaxSpareServers - Maximum number of idle child server processes MaxClients - Maximum number of child processes that will be created to serve requests MaxMemFree - Maximum amount of memory that the main allocator is allowed to hold without calling free() http://httpd.apache.org/docs/2.2/mod/prefork.html

11. Reading the Documentation Online: http://httpd.apache.org/docs/2.2/ Also installed with every instance of Apache Most directives consist of a name and a single value Some directives may have multiple, optional or boolean values Example directive:

12. Configuration File Syntax The default HTTPD.conf file contains a very good explanation of each directive that is used and why The directives are not ordered The configuration file contains one directive per line but the “\” may be used to indicate that the directive continues to the next line Configuration directives are case- insensitive but some arguments may be case- sensitive Lines that begin with “#” are considered to be comments <IfDefine> can be used to block out sections of the configuration file that are only used if a specific environment variable has been defined

13. HTTPD.conf Highlights ServerRoot – Base directory for the server installation All relative paths are derived from the ServerRoot If you have multiple installations of the web server, make sure that the ServerRoot points to the respective install locations PidFile - File where the server records the process ID of the daemon If an error message occurs when starting Apache on Linux indicating that HTTPD is already running, it may be that an old httpd.pid file was orphaned after an abnormal shutdown (ie. Kill -9)

14. HTTPD.conf Highlights Timeout – Amount of time the server will wait for send or receive events before failing a request (Default 300 seconds or 5 minutes) If Apache appears to hang during a shutting down on NetWare, it may be that a worker thread is waiting for data from the client. After the timeout period has expired, Apache will shutdown normally. KeepAlive – Enable persistent connections (ie. Avoids having to reconnect with the same client on sub-requests) If the connection is not properly terminated by the client, the connection will be held for the duration of the KeepAliveTimeout value. This could cause unecessary latency when responding to new requests on a busy server

15. HTTPD.conf Highlights Listen – Binds Apache to a specific IP address and/or port If only a port is specified, Apache will listen to that port on all IP addresses assigned to the box LoadModule – Loads an external Apache module <IfModule> - Should surround module specific directives to prevent invalid configuration if a module has not been loaded UseCanonicalName – Determines how Apache constructs self-referencing URLs (ie. Redirects) ServerName – Used to construct a self-referencing URL when UseCanonicalName is set to ON. Otherwise Apache uses the host name supplied by the client

16. HTTPD.conf Highlights DocumentRoot – Default location from which all documents are served If an alias for a URI is not found, Apache will attempt to serve the page from the DocumentRoot Options – Configures the features that are available in a specific directory Indexes – Allows a directory listing AddIcon - Specifies the location and file name of the icon that should be displayed for a given file type Multiviews – Allows language negotiation ExecCGI – Allow CGI binaries or scripts to be executed Includes – Enables Server-Side includes or parsed HTML

17. HTTPD.conf Highlights Order/Allow/Deny – Specifies access control restrictions The Order directive determines whether Apache should be inclusive or exclusive when applying access control Both Allow and Deny can be used to restrict access based on full or partial IP addresses, network masks or environment variables DirectoryIndex – Specifies the default file name(s) to serve when no page is specifed in the request The file index.html.var can be used to specify additional language negotiation rules rather than an actual web page

18. HTTPD.conf Highlights CustomLog – Defines the location and format of a custom log file When used with the LogFormat directive, the contents of the log file as well as the format can be specified Multiple log files can be defined containing different information or layouts (Warning: specifying additional log files may hurt performance) Alias – Associates a URI prefix with a physical directory location <Directory>/<Location>/<Files> - Should accompany the Alias directive to indicate how files are accessed from the aliased location

19. HTTPD.conf Highlights ErrorDocument – Defines a custom or user friendly response to an HTTP error The response can be in plain text, local redirect or external redirect If the response is a redirect, the language can be negotiated so that it is appropriate for the request BrowserMatch – Customizes the request handling for particular browsers Can be used to force a response to HTTP 1.0 rather than 1.1 or to turn off keepalive connections for older browsers

20. Modularizing the Configuration Functional blocks of directives can be put into a separate configuration file Use the “Include” directive to instruct Apache to read additional configuration files If the “Include” directive specifies a directory, all files within the directory will be read as additional configuration files Wildcards can be used to specify a certain set of additional configuration files (include conf/*.conf)

21. Virtual Hosts Apache supports two types of virtual hosts Name-based virtual host Selects a virtual host configuration based on the domain name of the request Allows more that one virtual host per IP address IP-based virtual Selects a virtual host configuration based on the IP address of the request Each IP address belongs to a specific virtual host Each virtual host can be configured independently ServerName, DocumentRoot, Aliases, log files, etc.

22. Name-Based Virtual Host NameVirtualHost *:80 <VirtualHost *:80> ServerName www.domain.com ServerAlias domain.com *.domain.com DocumentRoot /www/domain </VirtualHost> <VirtualHost *:80> ServerName www.otherdomain.com DocumentRoot /www/otherdomain </VirtualHost> NameVirtualHost specifies the IP address that will be shared ServerAlias directive allows access to a specific virtual host by different domain names Apache uses the ServerName directive to decide which virtual host configuration applies

23. IP-Based Virtual Host <VirtualHost www.smallco.com> ServerAdmin webmaster@mail.smallco.com DocumentRoot /groups/smallco/www ServerName www.smallco.com ErrorLog /groups/smallco/logs/error_log CustomLog /groups/smallco/logs/access_log combined </VirtualHost> <VirtualHost www.baygroup.org> ServerAdmin webmaster@mail.baygroup.org DocumentRoot /groups/baygroup/www ServerName www.baygroup.org ErrorLog /groups/baygroup/logs/error_log CustomLog /groups/baygroup/logs/access_log combined </VirtualHost> Apache determines which virtual host to use based off of the IP address Almost any configuration directive can be put in a virtual host block with the exception of some of the process creation directives

24. Language Negotiation A single instance of the Apache Web server can be used to serve page content in multiple languages Language negotiation does not depend on the server installed language The <Directory> or <Location> block must contain one of the following: “ Option Multiviews” to enable language file matching “ AddHandler type-map var” to specify a type-map file that contains language definitions Each HTML file encoded for a different language, must append the corresponding language extention Example: index.html.en – English, index.html.fr – French

25. Language Negotiation The following directives are used by the language negotiation functionality: - AddLanguage - DefaultLanguage - LanguagePriority - ForceLanguagePriority - AddDefaultCharset - AddCharset Each browser request contains an “accept-language” header that indicates the language(s) that the client will accept The languages are usually specified by either 2 or 4 character keys (en, en-us, fr, de, es, ...) - AddLanguage - DefaultLanguage - LanguagePriority - ForceLanguagePriority - AddDefaultCharset - AddCharset

26. How Language Negotiation Works Multiviews enabled negotiation Apache matches the “accept-language” key to a file extension through the “AddLanguage” directives in the HTTPD.conf file Apache first searches for an exact match of the specified file Apache next searches for the specified file with the 2 or 4 character appended language extension Type-Map enabled negotiation Apache searches for the specified file with the type-map extension (usually .var) Apache reads the .var file and selects the file name that is associated with the appropriate language If a language file is not found, Apache will fallback to the LanguagePriority and ForceLanguagePriority directives to determine how to handle the request More info: http://httpd.apache.org/docs/2.2/content-negotiation.html

27. <Directory> vs. <Location> Directives enclosed in a <Directory> block apply to the specified file system directory and sub-directories Directives enclosed in a <Location> block apply to the specified web space container <Location /private> would apply to any URL-path that begins with “/private” http://your.domain.com/private http://your.domain.com/private123 http://your.domain.com/private/mydocs/index.html Able to apply directives to locations that don't physically exist such as a module handler <Location /server-status> SetHandler server-status </Location>

28. SSL Encryption Default SSL port for an HTTP server is 443 All SSL requests and responses are handled through the MOD_SSL module (NetWare handles SSL natively) SSL configuration is done by creating a virtual host that listens the designated SSL port Example SSL configuration is found in conf/extra/httpd-ssl.conf of the Apache HTTPD distribution Additional documentation can be found at: http://httpd.apache.org/docs/2.2/ssl http://httpd.apache.org/docs/2.2/mod/mod_ssl.html

29. Modular Authentication Architecture Terms / Authentication Elements: Authentication Type – Type of encryption used during transport of the authentication credentials (Basic or Digest) Authentication Method/Provider – Process by which a user is verified to be who they say they are Authorization – Process by which authenticated users are granted or denied access based on specific criteria Previous to Apache 2.2, every authentication module had to implement all three elements Choosing an AuthType limited which authentication and authorization methods could be used Potential for inconsistencies across authentication modules Note: Pay close attention to the words Authentication vs. Authorization

30. New Modules - Introduction The functionality of each Apache 2.0 authentication module has been split out into the three authentication elements for Apache 2.2 Overlapping functionality among the modules was simply eliminated in favor of a base implementation The module name indicates which element of the authentication functionality it performs Mod_auth_xxx – Implements an Authentication Type Mod_authn_xxx – Implements an Authentication Method or Provider Mod_authz_xxx – Implements an Authorization Method

31. New Modules – Authentication Type AuthDigestAlgorithm AuthDigestDomain AuthDigestNcCheck AuthDigestNonceFormat AuthDigestNonceLifetime AuthDigestProvider AuthDigestQop AuthDigestShmemSize Mod_Auth_Digest MD5 Digest authentication – User credentials are received by the server in encrypted format AuthBasicAuthoritative AuthBasicProvider Mod_Auth_Basic Basic authentication – User credentials are received by the server as unencrypted data Directives Modules

32. New Modules – Authentication Providers AuthDefaultAuthoritative Mod_Authn_Default Authentication fallback module AuthDBMType AuthDBMUserFile Mod_Authn_DBM DBM file based user authentication Anonymous Anonymous_LogEmail Anonymous_MustGiveEmail Anonymous_NoUserID Anonymous_VerifyEmail Mod_Authn_Anon Allows “anonymous” user access to authenticated areas Directives Modules

33. New Modules – Authentication Providers AuthUserFile Mod_Authn_File File based user authentication AuthLDAPBindDN AuthLDAPBindPassword AuthLDAPCharsetConfig AuthLDAPDereferenceAliases AuthLDAPRemoteUserIsDN AuthLDAPUrl Mod_Authnz_LDAP LDAP directory based authentication Directives Modules

34. New Modules - Authorization AuthzDefaultAuthoritative Mod_Authz_Default Authorization fallback module Require ldap-user Require ldap-group Require ldap-dn Require ldap-attribute Require ldap-filter AuthLDAPCompareDNOnServer AuthLDAPGroupAttribute AuthLDAPGroupAttributeIsDN AuthzLDAPAuthoritative Mod_Authnz_LDAP LDAP directory based authorization Directives Modules

35. New Modules - Authorization Require file-group* Require group AuthDBMGroupFile AuthzDBMAuthoritative AuthzDBMType Mod_Authz_DBM DBM file based group authorization Allow Deny Order Mod_Authz_Host Group authorization based on host (name or IP address) Require file-group* Require group AuthGroupFile AuthzGroupFileAuthoritative Mod_Authz_GroupFile File based group authorization Directives Modules

36. New Modules - Authorization Require file-owner AuthzOwnerAuthoritative Mod_Authz_Owner Authorization based on file ownership Require valid-user Require user AuthzUserAuthoritative Mod_Authz_User User authorization Directives Modules

37. Differences Between Apache 2.0 & 2.2 New Directives AuthBasicProvider On|Off|provider-name [provider-name]… AuthDigestProvider On|Off|provider-name [provider-name]… AuthzXXXAuthoritative On|Off Renamed Directives AuthBasicAuthoritative On|Off Multiple modules must be loaded (auth, authn, authz) rather than a single mod_auth_xxx module

38. Differences – More Authorization Types Apache 2.0 Require Valid-User Require User user-id [user-id] … Require Group group-name [group-name] … Apache 2.2 Same as Apache 2.0 LDAP - ldap-user, ldap-group, ldap-dn, ldap-filter, ldap-attribute GroupFile – file-group* DBM – file-group* Owner – file-owner Since multiple authorization methods can be used, in most cases the type names should be unique

39. Configuring Simple Authentication LoadModule auth_basic_module modules/mod_auth_basic.so LoadModule authn_file_module modules/mod_authn_file.so LoadModule authz_user_module modules/mod_authz_user.so LoadModule authz_host_module modules/mod_authz_host.so <Directory /www/docs> Order deny,allow Allow from all AuthType Basic AuthName Authentication_Test AuthBasicProvider file AuthUserFile /www/users/users.dat require valid-user </Directory> The authentication provider is file based and the authorization method is any valid-user

40. Requiring Group Authorization LoadModule auth_basic_module modules/mod_auth_basic.so LoadModule authn_file_module modules/mod_authn_file.so LoadModule authz_host_module modules/mod_authz_host.so LoadModule authz_groupfile_module modules/mod_authz_groupfile.so <Directory /www/docs> Order deny,allow Allow from all AuthType Basic AuthName Authentication_Test AuthBasicProvider file AuthUserFile /www/users/users.dat AuthGroupFile /www/users/group.dat require group my-valid-group </Directory> The authentication provider is file based but the authorization method is group file based

41. Multiple Authentication Providers LoadModule auth_basic_module modules/mod_auth_basic.so LoadModule authn_file_module modules/mod_authn_file.so LoadModule authz_user_module modules/mod_authz_user.so LoadModule authz_host_module modules/mod_authz_host.so LoadModule authnz_ldap_module modules/mod_authnz_ldap.so LoadModule ldap_module modules/mod_ldap.so <Directory /www/docs> Order deny,allow Allow from all AuthType Basic AuthName Authentication_Test AuthBasicProvider file ldap AuthUserFile /www/users/users.dat AuthLDAPURL ldap://ldap.server.com/o=my-context AuthzLDAPAuthoritative off require valid-user </Directory> The authentication includes both file and LDAP providers with the file provider taking precedence followed by LDAP

42. Multiple Authorization Methods LoadModule auth_basic_module modules/mod_auth_basic.so LoadModule authn_file_module modules/mod_authn_file.so LoadModule authz_host_module modules/mod_authz_host.so LoadModule authz_groupfile_module modules/mod_authz_groupfile.so LoadModule authnz_ldap_module modules/mod_authnz_ldap.so LoadModule ldap_module modules/mod_ldap.so <Directory /www/docs> Order deny,allow Allow from all AuthType Basic AuthName Authentication_Test AuthBasicProvider file AuthUserFile /www/users/users.dat AuthzLDAPAuthoritative OFF AuthGroupFile /www/users/group.dat AuthLDAPURL ldap://ldap.server.com/o=my-context require ldap-group cn=public-users,o=my-context require group my-valid-group </Directory> Set AuthzLDAPAuthoritative to “OFF” to allow the LDAP authorization method to defer if necessary

43. New Features Already in Apache 2.3 Moving from hook-based to provider-based authorization “ AND/OR/NOT” logic in authorization Host Access Control as an authorization type Require IP …, Require Host …, Require Env … Require All Granted, Require All Denied “ Order Allow/Deny”, “Satisfy” where did they go? Backward compatibility with the 2.0/2.2 Host Access Control, use the Mod_Access_Compat module

44. Adding “AND/OR/NOT” Logic to Authorization Allows authorization to be granted or denied based on a complex set of “Require…” statements New Directives <SatisfyAll> … </SatisfyAll> - Must satisfy all of the encapsulated statements <SatisfyOne> … </SatisfyOne> - Must satisfy at least one of the encapsulated statements <RequireAlias> … </RequireAlias> - Defines a ‘Require’ alias Reject – Reject all matching elements

45. Authorization using ‘AND/OR’ Logic Configuration <Directory /www/mydocs> Authname ... AuthType ... AuthBasicProvider ... ... Require user John < SatisfyAll > Require Group admins Require ldap-group cn=mygroup,o=foo < SatisfyOne > Require ldap-attribute dept=&quot;sales“ Require file-group </ SatisfyOne > </ SatisfyAll > </Directory> Authorization Logic if ((user == &quot;John&quot;) || ((Group == &quot;admin&quot;) && (ldap-group <contains user>) && ((ldap-attribute dept==&quot;sales&quot;)|| (file-group contains user)))) then Authorization Granted else Authorization Denied

46. Questions

48. Unpublished Work of Novell, Inc. All Rights Reserved. This work is an unpublished work and contains confidential, proprietary, and trade secret information of Novell, Inc. Access to this work is restricted to Novell employees who have a need to know to perform tasks within the scope of their assignments. No part of this work may be practiced, performed, copied, distributed, revised, modified, translated, abridged, condensed, expanded, collected, or adapted without the prior written consent of Novell, Inc. Any use or exploitation of this work without authorization could subject the perpetrator to criminal and civil liability. General Disclaimer This document is not to be construed as a promise by any participating company to develop, deliver, or market a product. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. Novell, Inc. makes no representations or warranties with respect to the contents of this document, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. The development, release, and timing of features or functionality described for Novell products remains at the sole discretion of Novell. Further, Novell, Inc. reserves the right to revise this document and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes. All Novell marks referenced in this presentation are trademarks or registered trademarks of Novell, Inc. in the United States and other countries. All third-party trademarks are the property of their respective owners.