Understanding Apache 2.2 Configuration

1. Brad Nicholes Senior Software Engineer, Novell Inc. Member, Apache Software Foundation bnicholes@novell.com Understanding Apache 2.2 Configuration

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

32. New Modules – Authentication Providers

33. New Modules – Authentication Providers

34. New Modules - Authorization

35. New Modules - Authorization

36. New Modules - Authorization

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 Authorization Logic if ((user == "John") || ((Group == "admin") && (ldap-group <contains user>) && ((ldap-attribute dept=="sales")|| (file-group contains user)))) then Authorization Granted else Authorization Denied 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="sales“ Require file-group </SatisfyOne> </SatisfyAll> </Directory>

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.