Apache Cookbook Apache Con Europe 2007 Amsterdam Rich

Apache Cookbook Apache. Con Europe 2007 Amsterdam Rich Bowen - Asbury College rbowen@apache. org 1

Table of Contents SSL vhosts Rewrite based on query string Preventing “image theft” Logging more information Logging to syslog Web. DAV Preventing malicious requests with mod_security Enabling PHP Mass virtual hosting Customized error messages URL handler (“rewrite everything”) Fancy directory listings Caching dynamic content /server-info goodness /server-status goodness User. Dir without the ~

Recipes On CD At http: //people. apache. org/~rbowen/presentation s/apache_coobook_recipes. tar. gz 3

Caveat: Versions 2. 2 is the current version of Apache With any luck, by the end of the year, 2. 4 will be the current version of Apache If you are running 1. 3, you really should upgrade Some, not all, of these recipes will work in 2. 0 4

SSL vhosts Multiple SSL hosts, one IP address 5

Problem One SSL cert per IP address Certificate is negotiated before the HOST: header is sent 6

Solution Three options: Wildcard certificate Get more IP addresses Ignore the error messages 7

Wildcard certificate Costs $$$ Works for *. domain. tld Cannot span multiple domains Set up name-based vhosts the normal way 8

Wildcard certificate Name. Virtual. Host *: 443 # Wildcard certificate for *. domain. com SSLCertificate. File /var/www/conf/server. crt SSLCertificate. Key. File /var/www/conf/server. key <Virtual. Host *: 443> Server. Name one. domain. com Document. Root /var/www/one/htdocs SSLEngine On </Virtual. Host> <Virtual. Host *: 443> Server. Name two. domain. com Document. Root /var/www/two/htdocs SSLEngine On </Virtual. Host> 01_wildcard_cert 9

Multiple IP addresses This is the best solution Not always an option 10

Multiple IP addresses <Virtual. Host 172. 20. 4. 10: 443> Server. Name one. domain. com Document. Root /var/www/one/htdocs SSLCertificate. File /var/www/conf/one. crt SSLCertificate. Key. File /var/www/conf/one. key SSLEngine On </Virtual. Host> <Virtual. Host 172. 20. 4. 11: 443> Server. Name two. domain. com Document. Root /var/www/two/htdocs SSLCertificate. File /var/www/conf/two. crt SSLCertificate. Key. File /var/www/conf/two. key SSLEngine On </Virtual. Host> 02_ssl_hosts 11

Ignore errors SSL cert will be valid for only one hostname Other named vhosts will be encrypted Browser will report that the cert doesn’t match the hostname SSL is encryption + validation. You’re losing the validation. 12

Ignore the errors Name. Virtual. Host *: 443 # Certificate for one. domain. com SSLCertificate. File /var/www/conf/one. crt SSLCertificate. Key. File /var/www/conf/one. key <Virtual. Host *: 443> Server. Name one. domain. com Document. Root /var/www/one/htdocs SSLEngine On </Virtual. Host> # Will be secure, but will generate errors <Virtual. Host *: 443> Server. Name two. domain. com Document. Root /var/www/two/htdocs SSLEngine On </Virtual. Host> 03_ssl_vhosts 13

Other options Efforts are underway to escape this limitation Browser support is the big hurdle 14

Rewrite based on QUERY_STRING or PATH_INFO Sometimes what gets asked is: “I want to forbid access if the QUERY_STRING doesn’t contain foo=bar” 15

Rewrite by QUERY_STRING The sensible solution would be to handle this in your script/handler/program But, if that’s not an option, mod_rewrite might be a good choice 16

Problem Rewrite. Rule doesn’t have access to the QUERY_STRING Only the URI - the bit after http: //hostname. com and before the ? - is accessible to Rewrite. Rule 17

Solution Rewrite. Cond has access to the entire requested URL, and any other server variables Rewrite. Cond %{VARIABLE} regex 18

$Rewrite. Cond Does the QUERY_STRING contain foo=bar Rewrite. Cond %{QUERY_STRING} foo=bar Rewrite. Rule ^$

Rewrite. Cond Does the QUERY_STRING contain foo=bar Rewrite. Cond %{QUERY_STRING} foo=bar Rewrite. Rule ^ - [F] 04_query_string 19

^ rather than. * ^ means “starts with” All strings start, even empty strings. Thus, all strings match ^ ^ is more efficient than. * 20

Backreferences Or, you can do a rewrite based on the value of the QUERY_STRING Rewrite. Cond %{QUERY_STRING} user=(. +)b Rewrite. Rule (. *) /home/%1/www$1 05_query_string 21

More frequently. . . People want to map http: //example. com/one/two/three to http: //example. com/something. php? a=one&b=t wo&c=three 22

See also Upcoming recipe “URL Handler” Not quite the same, but many similar techniques 23

PATH_INFO Everything after the final / is the path info “Final /” refers to the / following an actual file or resource http: //example. com/index. php/one/two/three 24

PATH_INFO The trick is to figure out which bit is a valid resource, and which bit is PATH_INFO Two approaches 25

URL Prefix http: //example. com/prefix/one/two/three You know that only URLs starting with prefix need special attention Rewrite. Rule ^/prefix(. *) /handler. php? args=$1 06_rewrite 26

File existance Check to see if the requested file exists If not, rewrite May interfere with other rewrite matches Rewrite. Cond %{REQUEST_FILENAME} !-f Rewrite. Cond %{REQUEST_FILENAME} !-d Rewrite. Rule (. *) /handler. php? args=$1 07_rewrite 27

$Caveats May need to prepend a directory path Rewrite. Cond /var/www%{REQUEST_FILENAME} !-f Still$

Caveats May need to prepend a directory path Rewrite. Cond /var/www%{REQUEST_FILENAME} !-f Still need to do something useful with the value of $1, if you want it to be split into args. 28

The full recipe Rewrite. Rule ^/prefix/([^/]+) /handler. php? one=$1&two=$2 [PT, L] 08_rewrite 29

Caveats Exactly two arguments No more, no less Perhaps you want this to be more flexible? 30

More flexible Rewrite. Rule ^/prefix/([^/]+)? /? ([^/]+)? /handler. php? one=$1&two=$2 [PT, L] Matches are now optional Arguments will be passed null - just ignore them in handler. php, or check for null values and take appropriate measures 09_rewrite 31

More arguments This technique can be repeated for up to 9 arguments. $1 - $9 $10 is not available 32

Preventing image theft “Image theft” is the term used for other sites embedding your images in their pages. Ideally, you want to forbid having your images in any pages but your own There are several ways to accomplish this 33

Set. Env. If is provided by mod_setenvif Sets environment variables if certain conditions are met 34

Set. Env. If Referer “^http: //myhost. com” localref=1 <Files. Match ". (gif|jpg|png)"> Order Deny, Allow Deny from all Allow from env=localref </Files. Match> 10_image_theft 35

Problem Some browsers don’t set the Referer value Set. Env. If Referer “^http: //myhost. com” localref=1 Set. Enf. If Referer “^$” localref=1 <Files. Match ". (gif|jpg|png)"> Order Deny, Allow Deny from all Allow from env=localref </Files. Match> 11_image_theft 36

mod_rewrite Or, you could do it with a Rewrite. Rule Rewrite. Engine on Rewrite. Cond %{HTTP_REFERER} !="" Rewrite. Cond %{HTTP_REFERER} !example. com [NC] Rewrite. Rule . (jpe? g|gif|png)$ - [F, NC] 11_image_theft 37

But, more usefully If you’re just going to fail the request, use Set. Env. If. It’s more efficient But if you wanted to do something more interesting. . . 38

$Redirect the request Rewrite. Engine on Rewrite. Cond %{HTTP_REFERER} !="" Rewrite. Cond %{HTTP_REFERER} !example.$

Redirect the request Rewrite. Engine on Rewrite. Cond %{HTTP_REFERER} !="" Rewrite. Cond %{HTTP_REFERER} !example. com [NC] Rewrite. Cond %{REQUEST_URI} !go_away. png Rewrite. Rule . (jpe? g|gif|png)$ /images/go_away. png [NC, L] 13_image_theft 39

$Or. . . Rewrite. Engine on Rewrite. Cond %{HTTP_REFERER} !="" Rewrite. Cond %{HTTP_REFERER} !example.$

Or. . . Rewrite. Engine on Rewrite. Cond %{HTTP_REFERER} !="" Rewrite. Cond %{HTTP_REFERER} !example. com [NC] Rewrite. Rule . (jpe? g|gif|png)$ http: //othersite. com/images/unsavory. jpg [NC, R] 14_image_theft 40

Logging more information The standard log file is sometimes not sufficient. This recipe shows you how to get a little more information 41

mod_log_config Variables available for other values Always use ‘combined’ rather than ‘common’ 42

combined Log. Format "%h %l %u %t "%r" %>s %b "%{Referer}i" "%{User-Agent}i"" combined Custom. Log logs/access_log combined 15_combined 43

Additional variables http: //httpd. apache. org/docs/2. 2/mod_log _config. html#formats Most of the actual useful variables are already in ‘combined’ Most log analysis packages understand the ‘combined’ format 44

Important variables %{something}C - the value of the ‘something’ cookie %{something}i - the ‘something’ request (input) header %{something}o - the ‘something’ response (output) header %q - The query string and. . . 45

mod_logio %b gives the size of the response in bytes Does not include headers Does not include the request mod_logio gives both of these 46

mod_logio %I - total size of request (Input) in bytes %O - total size of response (Output) in bytes Includes headers in each case. 47

mod_dumpio http: //httpd. apache. org/docs/2. 2/mod_du mpio. html Dumps all input and output to the error log # Dump. IOLog. Level notice (2. 3) Dump. IOInput On Dump. IOOutput On 16_dumpio 48

mod_log_forensic http: //httpd. apache. org/docs/2. 2/mod_log _forensic. html Logs at the start, end of a request Uses unique IDs to match the two check_forensic script alerts you to requests that did not complete 49

Log. Level changes the level at which error messages are emitted Can increase/decrease the volume of your error_log In practice, this seldom adds useful information 50

Rewrite. Log Should always turn on the Rewrite. Log when Rewrite. Rules aren’t doing what you expect them to do Can only be turned on in main config, not in. htaccess files 51

Rewrite. Log logs/rewrite_log Rewrite. Log. Level 9 17_rewritelog 52

Other logs suexec SSL 53

Logging to syslog “Offsite” logs, in the event of catastrophe Multiple servers logging to the same place 54

Error. Log syslog. . . Error. Log syslog: local 0 55

Then, in /etc/syslog. conf local 0. * /var/log/error_log. . . local 1. * @192. 168. 1. 22: 32376 56

access_log mod_log_config doesn’t log to syslog Have to use piped log handlers 57

Solution Custom. Log |/usr/bin/apache_syslog combined Where the script looks like: #!/usr/bin/perl use Sys: : Syslog qw( : DEFAULT setlogsock ); setlogsock('unix'); openlog('apache', 'cons', 'pid', 'user'); while ($log = <STDIN>) { syslog('notice', $log); } 18_perl_syslog 58

. . . Sys: : Syslog is a standard Perl module, so you already have it installed Piped logging is a standard feature Script is started at server startup and remains running for the life of the server 59

Web. DAV Network filesystem over HTTP (or HTTPS) Manage your web content Access your files from anywhere Impress your friends 60

DAV Distributed Authoring Versioning 61

Modules mod_dav_fs . /configure --enable-modules=most --enable-mods-shared=all --enable-dav-fs 19_dav_configure 62

Recipe Dav. Lock. Db dav/davlock Alias /dav /var/www/dav <Directory /var/www/dav> Dav On </Directory> 20_dav 63

Accessing http: //servername. com/dav/ 64

Client applications Most modern operating systems cadaver - Simple command-line application Net. Drive - Windows Dav. Explorer - Java 65

For More Information Thursday morning Bill Rowe http: //www. eu. apachecon. com/program/talk/39 66

Caveat Files must be writeable by the Apache user This makes most of us VERY uncomfortable 67

Solution Run two Apache instances, with different permissions: Instance 1, runs as apache, content owned by dav Instance 2, runs as dav, has access to these directories Instance 2 runs over SSL, and is authenticated 68

Like. . . 1 User dav Group dav Document. Root /var/www <Directory /var/www> Dav On </Directory> User apache Group apache Document. Root /var/www> ls -lad. drwxrwxr-x 9 dav 306 Mar 23 22: 42. 69 2

Preventing malicious requests with mod_security modsecurity. org Apache module to do request filtering 70

New syntax Syntax has changed considerably in mod_security 2, so some of these recipes might not work quite as expected, depending on what version you’re using. 71

Core rules Download the core rules from http: //modsecurity. org/download/index. html Try to understand before using - this will avoid blocking desirable traffic 72

Basic Configs Turn on the engine Enable scanning of request body # Basic configuration options Sec. Rule. Engine On Sec. Request. Body. Access On Sec. Response. Body. Access Off 21_security 73

Trivial example # Trivial SQL blocking rule Sec. Default. Action log, auditlog, deny, status: 403, phase: 2, t: lowercase Sec. Rule REQUEST_URI|QUERY_STRING insert phase: 2 indicates that this runs after URL mapping. phase: 1 runs before URL mapping. t: lowercases the variable before comparison is applied 74 22_security

Sec. Rule VARIABLES OPERATOR [ACTIONS] ACTIONS is optional - Sec. Default. Action will be used Use multiple variables like REQUEST_URI|ARGS|QUERY_STRING OPERATOR is a regex match, by default 75

Note: mod_security is extremely powerful mod_security 2 adds a huge amount of new functionality and flexibility I’m just beginning to learn it, so you should go to the mailing lists with your questions http: //modsecurity. org/ 77

Enabling PHP There’s a certain amount of disagreement about the Right Way to do this So, if there’s any confusion, you should keep in mind one important rule of thumb 78

Rich is Right 79

Now that we’ve got that out of the way. . . 80

Add. Type associates a MIME type with a file extension It tells the browser how to display a particular type of content e. g. image/gif files should use the GIF rendering engine, and application/pdf files should use Adobe Acrobat 81

Add. Type image/gif. gif 82

Add. Handler tells the server how to process a certain type of file Calls a Handler which does something to the file before passing it along to the client 83

Add. Handler cgi-script. cgi 84

PHP is a handler However, PHP predates the Add. Handler directive, and so uses the Add. Type directive This is a grotty hack, and should be shunned 85

The right way: Add. Handler application/x-httpd-php. php 86

The other way Add. Type application/x-httpd-php. php 87

Multiple file extensions In either case, multiple file extensions can cause problems. foo. php. txt With php as a handler, it will still be executed With php as a mime type, it will lose its text/plain attribute 88

Discussion They both work Since it’s a handler, I recommend using Add. Handler Rasmus disagrees 89

Load. Module Must also ensure that the php module is loaded: Load. Module php 5_modules/libphp 5. so 90

Testing <? phpinfo(); ? > 91

92

Mass Virtual Hosting Several ways to do it Most of them are icky Don’t do this unless you really need to 93

When? When you have LOTS of vhosts Most of us don’t have that many vhosts Most of us are better of just making <Virtual. Host> blocks 94

Include Put each vhost in its own file Include them Include conf/vhosts/*. conf 000 Default. conf ZZZWildcard. conf 95

mod_vhost_alias Comes with Apache Very well documented Rather limiting 96

mod_vhost_alias Substitutes bits of the hostname into the directory path, using templates, like. . . 97

# %0 gives you the entire hostname: Virtual. Document. Root /var/www/%0 # www. example. com maps to # /var/www. example. com 24_vhost_alias 98

# %1 gives you the first part of the hostname: Virtual. Document. Root /var/www/%1 # www. example. com maps to # /var/www 25_vhost_alias 99

# %2 gives you the second part of # the hostname: Virtual. Document. Root /var/www/%2 # www. example. com maps to # /var/www/example 26_vhost_alias 100

# %3 gives you the third part of # the hostname: Virtual. Document. Root /var/www/%3 # www. example. com maps to # /var/www/com 27_vhost_alias 101

# And so. . . Virtual. Document. Root /var/www/%1/%2/%3 # www. example. com maps to # /var/www/example/com 28_vhost_alias 102

# -1, -2, -3 counts from the right Virtual. Document. Root /var/www/%-1/%-2 # www. example. com maps to # /var/www/com/example 29_vhost_alias 103

# m. n lets you choose particular letters Virtual. Document. Root /var/www/%-2. 1/%-2. 2/%-2. 3+ # www. example. com maps to # /var/www/e/x/ample 30_vhost_alias 104

# likewise. . . Virtual. Script. Alias /var/www/%-2. 1/%-2. 2/%-2. 3+/cgi # /cgi-bin maps to the directory # /var/www/e/x/ample/cgi # for www. example. com 31_vhost_alias 105

Advantages Don’t have to restart to add a new vhost All your vhosts are identical and predictable 106

Caveats All your vhosts must be identical You can’t intermix vhost_alias vhosts and regular vhosts on the same IP address mod_alias and mod_userdir always override vhost_alias directives 107

$Vhosts with mod_rewrite Rewrite. Engine On Rewrite. Cond %{HTTP_HOST} ^([^. ]). example. com$

Vhosts with mod_rewrite Rewrite. Engine On Rewrite. Cond %{HTTP_HOST} ^([^. ]). example. com Rewrite. Rule (. *) /var/www/%1$1 32_vhost_rewrite 108

Disadvantages May cause interactions with other Rewrite. Rules (like in. htaccess files) that may cause breakage. 109

Customized Error Messages Override the default boring error responses Less jarring to the user Give them useful information or links 110

Error. Document 404 /errors/404. html 111

Not always an error message Can be used as a “default document” when something is not found Error. Document 404 /index. html Error. Document 401 /register. html 112

Embedded logic Can contain basic embedded logic using SSI See extras/httpd-multilang-errordoc. conf for extended example 113

Embedded logic Alias /error /www/error <Directory /www/error> Options Includes. No. Exec Add. Output. Filter Includes html </Directory> Error. Document 404 /error/404. html 33_errordoc 114

Then 404. html is. . . <html> <head><title>Not Found</title></head> <body>  The link from  The URL you entered could not be found here.  </body> </html> 115 34_404

URL Handler (“Rewrite Everything”) One content handler for all requests 116

$Recipe Rewrite. Engine On Rewrite. Cond %{REQUEST_FILENAME} !-f Rewrite. Cond %{REQUEST_FILENAME} !-d Rewrite. Cond$

Recipe Rewrite. Engine On Rewrite. Cond %{REQUEST_FILENAME} !-f Rewrite. Cond %{REQUEST_FILENAME} !-d Rewrite. Cond $1 !=/handler. php Rewrite. Rule (. *) /handler. php [PT] 35_rewrite 117

handler. php would know what was actually requested by looking at $_SERVER[‘REQUEST_URI’] Other files (images, css, static files) are served as normal, due to the -f test. 118

Error. Document Can also be done with an Error. Document 404 /handler. php HOWEVER, Error. Documents can’t receive POST data, so this is a rather limited solution 119

Fancy Directory Listings Auto directory listings are ugly It would be nice to have more control over them 120

Suppress unwanted columns Index. Options Suppress. Last. Modified Suppress. Description 36_indexoptions 121

Insert “wrapper” html Index. Options Suppress. HTMLPreamble Header. Name /style/header. html Readme. Name /style/footer. html 37_indexoptions 122

Wrapper <html> <head><title>Directory Listing</title> </head> <body> 38_header. . . Listing goes here. . . </body> </html> 39_footer 123

CSS Index. Style. Sheet "/css/style. css" 40_css 124

Caching Dynamic Content Much of your ‘dynamic’ content doesn’t change very often Cache it to improve performance 125

Warning Caching dynamic content, by definition, causes stale content to be served Note that “private” content will not (usually) be cached 126

Cache for 10 minutes Cache. Root /usr/local/apache/cache Cache. Enable disk / Cache. Dir. Levels 5 Cache. Dir. Length 3 # Cache stuff for 10 minutes Cache. Default. Expire 600 Cache. Ignore. Cache. Control On 41_cache 127

Cleaning the cache There are two ways to clear the cache Depending on how much you care. . . 128

htcacheclean Cleans up your cache periodically Can specify an upper limit on size -t deletes empty directories (in the cache) htcacheclean -d 10 -p /var/cache/apache -l 50 M -t 129

httacheclean Runs every 10 minutes (or whatever you specify) Keeps cache below 50 M (or whatever. . . ) Purges older content first 130

rm -rf If you don’t care about gradually expiring content, just delete everything in the cache directory Faster - if you need to quickly purge the cache 131

/server-info goodness mod_info gives useful information about your server configuration 132

Configuration <Location /server-info> Set. Handler server-info # Order deny, allow # deny from all # allow from 192. 168 </Location> 133

Security considerations Should protect this resource Don’t give crackers additional information 134

/server-info 135

/server-info? config 136

? config Includes Include’ed files Shows line numbers, file names 137

? config Particularly useful on third-party distros of Apache with unfamiliar config file layout Locate overlapping or conflicting configuration settings 138

? server 139

? server Equivalent to httpd -V 140

? list 141

? hooks 142

And if you select one. . . That’s ? mod_log_config. c 143

/server-status goodness Displays the current status of the server Also some basic statistical reports 144

Configuration <Location /server-status> Set. Handler server-status # Order deny, allow # deny from all # allow from 192. 168 </Location> 145

Security As with /server-info, protect Also, reveals what users are looking at what content 146

Extended. Status On Gives more information 147

/server-status 148

Or, more interesting. . . 149

Extended. Status 150

/server-status? auto Machine-readable Useful for things like mrtg 151

Example mrtg script #!/usr/bin/perl use LWP: : Simple; $content = get("http: //localhost/server-status? auto"); $content =~ m/Busy. Workers: (d+)/s; print $1. "n"; $content =~ m/Idle. Workers: (d+)/s; print $1. "n"; 42_mrtg 152

/server-status? refresh=4 Automatically refreshes every N seconds Or, combine them: http: //rocinante. rcbowen. com/server-status? auto&refresh=2 Not sure what that’s useful for. . . 153

User. Dir without the ~ Using mod_rewrite to create a per-user URL, without the ~ 154

Problem We want: http: //example. com/username/foo To work the same as: http: //example. com/~username/foo 155

But Somehow, . . . http: //example. com/not-a-username/foo still needs to work properly 156

-d Rewrite. Engine On # If that home directory exists. . . Rewrite. Cond /home/$1 -d Rewrite. Rule ^/([^/]+)/(. *) /home/$1/www/$2 43_userdir 157

How this works Rewrite. Engine On Rewrite. Cond /home/$1 -d Rewrite. Rule ^/([^/]+)/(. *) /home/$1/www/$2 That’s right, $1 is used in the Rewrite. Cond before it is defined in the Rewrite. Rule Pretty cool, hmm? 158

Huh? Rewrite. Rules are always evaluated before the corresponding Rewrite. Conds You can watch this in the Rewrite. Log: 159

http: //example. com/rbowen/index. html (3) applying pattern '^/([^/]+)/(. *)' to uri '/rbowen/index. html' (4) Rewrite. Cond: input='/home/rbowen' pattern='-d' => matched (2) rewrite '/rbowen/index. html' -> '/home/rbowen/www/index. html' (2) local path result: /home/rbowen/www/index. html (1) go-ahead with /home/rbowen/www/index. html [OK] 160

That’s all, folks rbowen@apache. org http: //people. apache. org/~rbowen/ 161