Zeus Web Server 4.3 User Guide

Transcription

1 Zeus Web Server 4.3 User Guide

2 Zeus Technology Limited - COPYRIGHT NOTICE Zeus Technology Limited Copyright in this documentation belongs to Zeus Technology Limited. All rights are reserved. This documentation may not be reproduced in whole or in part in any manner or form (including photocopying or storing it in any medium by electronic means and whether or not transiently or incidentally to some other use of this documentation) other than in accordance with any applicable licence agreement or with the prior written consent of Zeus Technology Limited. Any copies of this documentation must incorporate this notice. Zeus Technology, the Zeus logo, Zeus Web Server (ZWS), Zeus Load Balancer (ZLB) and Zeus Extensible Traffic Manager (ZXTM) are trade marks of Zeus Technology Limited. Other trade marks used may be owned by third parties. Adobe, Acrobat and Acrobat Reader are trademarks of Adobe Systems Incorporated. Microsoft, FrontPage and Internet Explorer are registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Netscape and Netscape Navigator are registered trademarks of Netscape Communications Corporation in the United States and other countries. Zeus Technology Ltd The Jeffreys Building Cowley Road Cambridge CB4 OWS United Kingdom Phone: +44 (0) Fax: +44 (0) info@zeus.com Web:

3 Table of Contents CHAPTER 1 Overview Introducing Zeus Web Server API Support and Integration Intended Audience Introducing this Manual Road Map Version Information Documentation Conventions Further Information CHAPTER 2 Basic Concepts Introduction Web Servers Introducing Web Servers Web Server Functionality Zeus Web Server Functionality Virtual Servers Introducing Virtual Servers Types of Virtual Servers Managing Virtual Servers using Zeus Web Server Clusters Introducing Clusters Managing Clusters with Zeus Web Server Subservers Introducing Subservers Managing Subservers using Zeus Web Server Bandwidth Throttling Web Server Security Introducing Web Server Security Introducing Private Keys Introducing Signed Certificates i

4 Introducing Self-Signed Certificates...35 Zeus Web Server Security Support Logging Monitoring Activity Script-Based Management...38 CHAPTER 3 Starting Zeus Web Server Introduction Starting and Stopping Zeus Web Server...41 Starting Zeus Web Server...41 Stopping Zeus Web Server...42 Starting and Stopping Individual Components Setting Up your Browser and Reader Accessing the Zeus Web Server Interface Pages Preparing to Publish a Web Site Creating a New Virtual Server Using the Virtual Server Status Page...50 Overview of the Virtual Server Status Page Layout...50 Starting and Stopping a Virtual Server...52 Committing Configuration Changes Publishing a Web Site Viewing Your Web Site...53 Basic Tasks Introduction Configuring Virtual Servers...55 Configuring One Virtual Server...55 Modifying Multiple Virtual Servers Grouping Virtual Servers...56 Creating a Group...57 Changing the Members of a Group...58 Adding Virtual Servers to an Existing Group...59 Configuring a Group...59 Searching for a Virtual Server...59 CHAPTER 4 ii

5 4.4 Monitoring Virtual Servers and Groups Monitoring Virtual Servers Monitoring Groups Committing Configuration Changes Starting and Stopping Virtual Servers Resolving Problems Using the Diagnose Icon Deleting Items Deleting Virtual Servers Deleting Groups Licensing Web Server Machines Licensing Mechanisms Viewing Server License Details Updating a Web Server License Setting up Virtual Server SSL Security Using Certificate Sets Creating a Certificate Set Entering Certificate Set Information Importing Existing Files into a Certificate Set...71 Managing Certificate Sets...71 Deleting a Certificate Set Issuing a Certificate Signing Request Real-Time Monitoring Selecting Which Events to Monitor Configuring the Graph Grouped Reports Current Connections Using the Traffic History Pages Using the Traffic Overview Page Using the Web Site Comparison Page Using the Cluster Traffic Analysis Page Configuring your Preferences Configuring Administration Security Sending a Technical Support Query iii

6 CHAPTER 5 Configuring Virtual Server Functionality Introduction Functionality Overview Using the Configuration Pages...89 Overview of the Layout of the Configuration Pages...89 Configuring a Single Virtual Server...91 Configuring Multiple Virtual Servers...91 Resolving Errors and Warnings...93 Indicator Summary...93 CHAPTER 6 General Configuration Information Introduction Viewing the Configuration Summary...96 Renaming a Virtual Server Viewing the Request Processing Summary...96 Request Processing reference Fundamental Configuration Settings Advanced Configuration Settings Configuring SSL Security for a Virtual Server Enabling SSL Support for a Virtual Server Creating an SSL Server Certificate Set Using SSL Client Certificates Why are SSL Client Certificates useful? Configuring the Locations of Public Certificates and Revocation Lists Reloading a Virtual Server with updated certificates and CRLs104 Configuring File Handling Introduction Configuring MIME Types Configuring the Default MIME Type Adding a MIME Type Deleting a MIME Type Modifying a MIME Type CHAPTER 7 iv

7 Automatic MIME Type Detection Configuring Content Negotiation How Users Configure Browsers for Content Negotiation How Content Negotiation Works Naming Files How Users Request Files Linking between Pages How Files are Returned Types of Content Negotiation Configuring Content Negotiation on the Virtual Server Configuring Language Negotiation Modifying an Assigned Language Code Deleting an Assigned Language Code Configuring Character Set Negotiation Modifying an Assigned Character Set Code Deleting an Assigned Character Set Code Configuring Encoding Negotiation Modifying an Assigned Encoding Deleting an Assigned Encoding Configuring MIME Type Negotiation Designing a Web Site to use Content Negotiation Adapting an Existing Web Site to use Content Negotiation Language Content Negotiation of HTTP Error Pages Configuring Content Compression Introducing Content Compression Enabling Content Compression Configuring which MIME types to Compress Configuring Static Content Compression Configuring Dynamic Content Compression Configuring File Uploading Controlling Security Controlling File Ownership CHAPTER 8 Configuring URL Handling Introduction v

8 8.2 Configuring URL Mapping Creating an Alias Deleting an Alias Editing an Alias Configuring Gateway Aliases Adding a Gateway Alias Rewriting HTTP Redirects Rewriting HTTP Cookies Deleting a Gateway Alias Changing a Gateway Alias Rewriting the URL before forwarding Configuring Home Directories Changing the Web Page Subdirectory Changing the Username Prefix Configuring Username to Home Directory Mapping Using the Standard passwd File Using a File Similar to /etc/passwd If All Home Directories are in a Single Subdirectory Using an LDAP Server Configuring Directory Requests Configuring Index Files Configuring Directory Listings Changing the Directory Listing using htaccess Configuring Handlers Adding a New Handler Configuring Request Rewrite Scripts Using Request Rewrite Scripts Syntax of the Scripting Language Scripting Language Variables Scripting Example using Variables Scripting Language Commands Scripting Language Labels Scripting Language Strings Scripting Language Comments Nesting Commands in Scripts vi

9 Developing Request Rewrite Scripts Entering a Request Rewriting Script Running a Script Debugging Scripts Configuring Compiler Information Configuring Debugging Information Overwriting the Request URI Stopping a Script in a Loop Converting from Existing Apache mod_rewrite Scripts Configuring Spelling Correction Configuring the Spelling Correction Functionality Configuring Response Headers Configuring the Response Headers Functionality Response Headers example Response Headers macros Example: Setting an Expires time for images CHAPTER 9 Configuring Logging and Monitoring Introduction Configuring Request logging Configuring the Log File Format Using a Custom Format String Configuring Conditional Logging Logging SSI Requests Consolidating and Splitting Multiple Request Log Files Error Handling Customizing HTTP Error Pages Specifying the HTTP Error Page Location Adding Dynamic Content to HTTP Error Pages Generating Error Pages in Third-Party Applications Advanced Control of HTTP Error Pages Configuring the Error Log File Location Traffic History Statistics Gathering Configuring User Tracking Configuring User Tracking vii

10 Specifying Cookie Names Configuring Cookie Lifetimes Specifying Optional Cookie Domains Analyzing Cookie Results Configuring Forensic logging Example log entries Analyzing the Forensic log file Configuring SNMP monitoring Enabling reporting via SNMP Variables reported via SNMP Setting SNMP security SNMP variable behaviour CHAPTER 10 Configuring Access Introduction Configuring Access Rules Background Types of Access Control Introducing Access Rules How Zeus Web Server Applies Access Rules Configuring the Access Rules: Overview Specifying the User Database Configuring Access Users in the Internal Database Configuring Access Groups in the Internal Database Using an LDAP Database Using an Operating System Lookup Configuring Access Rules Specifying Host Names and IP Addresses Modifying Rules Re-ordering Rules Debugging Rules Using htaccess Files Background Introducing.htaccess Files Enabling and Configuring htaccess File Functionality viii

11 Supported htaccess Directives Enabling Automatic Headers and Footers Adding Common Headers to Web Pages Adding Common Footers to Web Pages Configuring Bandwidth Throttling Setting a Throttling Limit Configuring Who Can Refer to Your Content Configuring Referrer Checking Redirecting Denied Requests Allowing Specified Web Sites to Use Your Bandwidth Denying Requests with no Referrer Header CHAPTER 11 Configuring API Support Introduction Configuring SSI Support Introducing SSI Using SSI Directives Configuring SSI Support Configuring SSI Handlers Configuring CGI Support Introducing CGI Simple Example Setting up a CGI Script Directory Enabling and Configuring General CGI Support Restricting CGI Script Locations Configuring Aliases for CGI Script Directories Configuring Additional CGI Environment Variables Configuring CGI Error Logging Configuring Additional CGI Settings Configuring CGI Sandboxing Specifying CGI Configurables Running Multiple Scripts Concurrently Specifying the Security Configurables Configuring chroot Jails Configuring Support for FastCGI ix

12 Introducing FastCGI Running FastCGI Applications Comparing FastCGI with CGI Further Information about FastCGI Enabling and Configuring FastCGI Support Restricting FastCGI Locations Configuring FastCGI Concurrency Configuring FastCGI Security Settings Configuring Local Responder Script Directories Configuring Remote Responder Script Directories Configuring Authorizers Configuring Remote Scripts to Start Configuring Additional FastCGI Environment Variables Configuring ISAPI Support Introducing ISAPI Introducing ISAPI Server Extensions Introducing ISAPI Filters Running ISAPI Applications In-Process and Out-of-Process Comparing ISAPI with CGI Further Information about ISAPI Enabling and Configuring ISAPI Support Configuring ISAPI Extension Directories Configuring In-Process and Out-of-Process Extensions Registering In-Process ISAPI Filters Registering Out-of-Process ISAPI Filters Configuring Java Servlet Support Introducing Java Servlets Introducing the Virtual Server s Java Servlet Support Enabling and Configuring Java Servlets Support Adding a Java Servlet Mount Point Accessing Servlets Configuring NSAPI Support Introducing NSAPI Overview of the NSAPI Interface Enabling and Configuring NSAPI Support x

13 Configuring the NSAPI Configuration File Directory Configuring NSAPI Sandboxing The NSAPI Runner Configuring Support for the ZDAC API Introducing ZDAC Introducing the ZDAC Authentication API Introducing the ZDAC Content API Further Information about ZDAC Enabling and Configuring ZDAC Support Specifying the ZDAC Content Directory Configuring a Content Generator Configuring an Authorizer CHAPTER 12 Configuring Subservers Introduction Concepts Subserver Directory Structure Directory Structure Prefix and Suffix Creating Subservers Using Subservers Publishing a Web Site on a Subserver Configuring the DNS for Subservers Viewing a Subserver s Web Site Deleting a Subserver Advanced Subserver Configuration Enabling Default Subservers Automatic Webmaster Address Using a Custom Subserver Mapping Function Using Subservers with Older Browsers Request Logging for Individual Subservers CGI Logging for Individual Subservers Using Global.htaccess with Subservers xi

14 CHAPTER 13 Configuring Add-Ons Introduction Configuring the Search Engine Configuring the Search Engine Functionality Generating the Search Index File Accessing the Search Page Updating the Search Index File Excluding Files from the Search Controlling how the Search Engine Treats Files Customizing the Appearance of the Search Engine Configuring Server-Side Imagemaps Configuring FrontPage Introducing FrontPage Functionality Introducing the FrontPage Extensions Pre-Requisites Downloading and Installing the FrontPage Extensions Enabling and Configuring FrontPage Support Configuring the FrontPage Forms Interface Disabling a FrontPage Installation Configuring Additional FrontPage Extension Directives Moving a FrontPage Installation Chrooting a FrontPage Installation Configuring PHP Introducing PHP Configuring PHP Configuring Concurrency and Security Settings Using your own PHP handler CHAPTER 14 Using Clusters Introduction Creating a Cluster of Web Servers Installing an Administration Server Installing Zeus Web Server across the Cluster Checking the Cluster Configuration xii

15 Configuring Request Distribution within the Cluster Publishing a Web Site on a Cluster Changing the Cluster Configuration Adding a Web Server to a Cluster Removing a Web Server from a Cluster Returning a Web Server to a Cluster Deploying Configuration Files to a New Web Server in a Cluster290 Customizing Virtual Servers for Different Web Servers Monitoring Clusters Viewing the Cluster Configuration Viewing the Activity on a Specific Web Server on a Machine.292 CHAPTER 15 Using Zeus Perl Extensions Introduction Getting started with Zeus Perl Extensions Installed files Installation of Perl modules Configuring Zeus Perl Extensions Enabling #perl in SSI Configuring additional Library Paths Configuring the Logging Level Migrating existing Perl modules htaccess directives The Perl Startup File Using webctl with Zeus Perl Extensions The apache2zeus conversion utility Zeus::ModPerl::Registry Differences from the Apache Perl API CHAPTER 16 Configuring Global Information Introduction Global Functionality Overview Using the Global Settings Pages Overview of the Layout of the Global Setting Pages xiii

16 16.4 Configuring the Service Protection System Introducing Basic Service Protection Concepts Enabling and Configuring the Service Protection System Specifying Debug Logging Options Testing Protection Settings Introducing Request Filtering Configuring Request Filtering Rules Adding a Single Request Filtering Rule Adding Multiple Request Filtering Rules Modifying Individual Request Filtering Rules Modifying Individual Request Filtering Rules Deleting Rules Importing and Exporting Rules using text files Configuring Advanced Request Filtering Options Introducing Connection and Rate Limits Limiting Users Concurrent Connections Limiting User s Connection Rates Advanced monitoring of Connection Limiting Connection Limiting Error Log Messages APPENDIX A HTTP Status Codes 323 A.1 HTTP Status Codes APPENDIX B Using htaccess Directives 325 B.1 Introduction B.2 Configuring.htaccess Files htaccess File Format How Zeus Web Server Applies Directives B.3 Supported Directives B.4 Types of Directives B.5 Section Directives How Errors in Section Directives are Handled Nesting Section Directives Pattern Matching in Section Directives xiv

17 The Include Directive B.6 Header Directives The Header Directive The AddType Directive The ForceType Directive The DefaultType Directive The Redirect Directive The ServerAdmin Directive B.7 Expires Directives The ExpiresActive Directive The ExpiresDefault Directive The ExpiresByType Directive B.8 Directory Listing Directives The DirectoryIndex Directive The IndexIgnore Directive B.9 HTTP Error Page Directives The ErrorDocument Directive B.10 Handler Directives The AddHandler Directive The SetHandler Directive The RemoveHandler Directive B.11 CGI Script Directives CGI Sandboxing Directives CGI Security Directives B.12 Environment Directives The SetEnvIf Directive The SetEnvIfNoCase Directive The BrowserMatch Directive The BrowserMatchNoCase Directive B.13 Access Control Directives Controlling Access using Deny, Allow and Order Password Protecting Areas of the Web Site User-Based Access Control Directives Building up Sophisticated Access Rules Satisfy Directive xv

18 B.14 Restriction Directives The Options Directive The AllowOverride Directive B.15 Directory Mapping Directives The Alias Directive The ScriptAlias Directive The FastCGIAlias Directive The ISAPIAlias Directive B.16 Zeus Extensions to the Apache Specification The PassEnvAuthorization Directive Content Compression Directives B.17 Perl directives PerlScript <path> PerlRequire <path> PerlModule <module-name> PerlSetEnv <name> <value> PerlSetVar <name> <value> PerlAddVar B.18 Perl Handler Directives PerlHeaderParserHandler PerlInitHandler PerlAccessHandler PerlAuthenHandler PerlAuthzHandler PerlTypeHandler PerlFixupHandler PerlHandler PerlLogHandler PerlCleanupHandler APPENDIX C Scripting Overview 369 C.1 Introduction C.2 Script Location The ZEUSHOME Environment Variable Script Directories xvi

19 Viewing Zeus Web Server Man Pages C.3 Script Overview Creating, Deleting and Controlling Virtual Servers Error Tracking and Testing Miscellaneous Functions C.4 The webctl Script Webctl Syntax Committing Configuration Changes to a Virtual Server Starting, Stopping and Restarting Virtual Servers Synchronizing a Cluster Listing which Web Servers are in a Cluster Reloading Certificate Validation Information C.5 The addserver.sh Script C.6 The delserver.sh Script C.7 The errormailer Script C.8 The subserver_logsplit.pl Script C.9 The blf2clf Program C.10 The httpclient Program C.11 The gzipcache Program C.12 The fpinst.sh Script FrontPage Installation Script Command-Line Options FrontPage Installation Script Command-Line Parameters C.13 The Virtual Server Configuration Files Configuration File Format Location of Configuration Files The Skeleton Configuration File Using a Changed Configuration File C.14 The Global Configuration File Global Configuration File Format Changing the Global Configuration File C.15 The Dynamic Global Configuration File APPENDIX D Using Regular Expressions 389 D.1 Overview D.2 Syntax xvii

20 Examples Glossary Index xviii

21 CHAPTER 1 Overview 1.1 Introducing Zeus Web Server Zeus Web Server is a high performance web server with a scalable architecture that can host tens of thousands of web sites on a single machine. It provides a reliable, secure web server that can handle tens of thousands of simultaneous connections and provides leading end-user response times and transaction throughput. Its flexible functionality can easily be integrated with existing systems, and its comprehensive and intuitive web-based configuration, management and administration system enables you to configure and run multiple web sites easily, either locally or remotely, using a web browser. The web-based user interface supports web server clusters and centralized user management, enabling cost-effective administration of complex distributed web server infrastructures. In addition to using the user interface, you can also manage and configure Zeus Web Server from the command line, and from scripts. Zeus Web Server is designed for, and used by, businesses that are supporting mission-critical web sites, where speed and reliability are key. This includes Business-to-Business and Business-to-Consumer commerce sites, Internet Content Providers/Portals, ISPs offering shared web hosting services, and corporate Intranets. It also integrates seamlessly with other Zeus products, providing a straightforward migration and upgrade path to our Traffic Management and Mass Hosting products. Overview 19

22 API Support and Integration The web provides an accessible development platform, based upon open standards, that ensures interoperability between applications. Zeus Web Server supports the following open-standard APIs: Server Side Includes (SSI) SSI provides a simple means of organizing and managing web sites and is used extensively to provide attractive dynamic content. Zeus Web Server contains a powerful, efficient, recursive SSI parsing engine that significantly expands how SSI functionality can be used. For more information, see Configuring SSI Support on page 210. Secure CGI sandbox system Zeus Web Server is fully CGI/1.1 compliant and uses a unique sandbox environment to execute CGI programs safely by applying fine grain restrictions to CGI programs. It can place limits on the machine resources that CGI processes can consume, run programs under different UNIX IDs and run them in secure 'chroot' jails. For more information, see Enabling and Configuring General CGI Support on page 215. FastCGI FastCGI is an open standard for generating dynamic web content and authenticating access to web sites. It is an extension of the existing CGI standard, that eliminates many of its weaknesses. Zeus Web Server fully supports FastCGI applications. For more information, see Configuring Support for FastCGI on page 224. ISAPI The Internet Server Application Programmers Interface (ISAPI) provides a vendor-independent way of extending the functionality of your web server. It is a widely-supported Microsoft-backed standard. Zeus Web Server fully supports ISAPI extensions and filters on all platforms and architectures. For more information, see Configuring ISAPI Support on page 236. Java Servlets Java s threaded nature and object inheritance make it ideal for many web applications. Their platform independence enables Java Servlets to be distributed across a cluster of machines easily, which can include specialized machines that are optimized for the Java language, resulting in both 20 Overview

23 increased performance and system robustness. Zeus Web Server provides Java Servlet support through native Jserv/Tomcat and JRun interfaces. For more information, see Configuring Java Servlet Support on page 242. NSAPI NSAPI is a powerful, comprehensive web development toolkit with thirdparty support. Zeus Web Server provides NSAPI support to enable seamless migration of web applications written for Netscape Enterprise Server. For more information, see Configuring NSAPI Support on page 245. Zeus Perl Extensions The Zeus Perl Extensions provide an interface to allow specially written Perl modules to interface with Zeus Web Server. The interface provides a rich layer of interaction with HTTP requests and headers, and is designed to provide a very high level of performance, which is much faster than using Perl in CGI scripts. For more information, see Using Zeus Perl Extensions on page 295 Zeus Distributed Authentication and Content API The Zeus Distributed Authentication and Content API (ZDAC) enables the web server to interact with external authentication servers and content generation servers over a TCP/IP socket interface. For more information, see Configuring Support for the ZDAC API on page 248. FrontPage Zeus Web Server offers full support for Microsoft's and Netscape's web publishing applications. Microsoft FrontPage support is available on all Microsoft-supported UNIX platforms. For more information, see Configuring FrontPage on page 274. PHP/Zend PHP is an open-source server-side scripting language for creating dynamic Web pages for e-commerce and other web applications. Zeus Web Server provides a high-performance platform through the FastCGI interface. For more information, refer to the Zeus support web site, Overview 21

24 1.2 Intended Audience This manual is aimed at customers who are running Zeus Web Server. The chapters assume that you are familiar with basic web server functionality, and simple UNIX commands. The appendices contain more advanced information. These assume that you are familiar with the UNIX command line and simple scripts. 1.3 Introducing this Manual This manual introduces the basic concepts to help you understand and use Zeus Web Server effectively. It then describes how to use it and provides a comprehensive guide to all its functions. Please send any feedback on this manual to docs@zeus.com. Road Map The Basic Concepts chapter introduces fundamental web server concepts and describes the functionality that Zeus Web Server provides. Read this chapter if you are unfamiliar with web server functionality or if you would like to read an overview of the Zeus Web Server functionality. The Starting Zeus Web Server chapter describes how to start Zeus Web Server, how to access its user interface pages and how to create a Virtual Server. The Basic Tasks chapter describes how to use Zeus Web Server to carry out basic tasks. It assumes that you have already created your first Virtual Server, and describes how to modify, monitor and manage multiple Virtual Servers, and how to set up secure communication for them using SSL. It 22 Overview

25 also describes how to use the administration pages and how to enable them to use SSL. The Configuring Virtual Server Functionality chapter provides an overview of the functionality that can be configured for each Virtual Server and describes how to enable and disable it. The General Configuration Information chapter describes how to view and configure the Virtual Server s general configuration information. The Configuring File Handling chapter describes the different ways in which you can configure the Virtual Server to handle requests for different files (or file types), and how it returns files to users. The Configuring URL Handling chapter describes the different ways in which you can configure the Virtual Server to handle requests for different URLs. The Configuring Logging and Monitoring chapter describes how you can monitor the performance of your web sites, and track how people are using them. The Configuring Access chapter describes how to configure web site accessibility, in a number of different ways. The Configuring API Support chapter introduces the APIs that Zeus Web Server supports and describes how to configure a Virtual Server to support applications written using them. The Configuring Subservers chapter describes how to set up and use a Virtual Server that supports Subservers, and the different Subserver directory structures that you can use. The Configuring Add-Ons chapter describes how to integrate the Virtual Server with a number of different add-ons, such as FrontPage, the search engine, and the spelling correction functionality. The Using Clusters chapter describes how to create, modify and monitor a cluster. Overview 23

26 The Using Zeus Perl Extensions chapter describes how to use the Zeus Perl Extensions. The HTTP Status Codes appendix lists the standard HTTP status codes supported by Zeus Web Server. The Scripting Overview appendix describes the scripts, commands and programs that are available, and how to use them. It also describes the format and the location of the Zeus Web Server configuration files. The Using htaccess Directives appendix outlines the.htaccess file format, and describes the supported directives and how to use them. The Using Regular Expressions appendix introduces regular expressions and describes how to use them to specify IP addresses and host names. Version Information This manual describes the functionality of, and uses screen shots from, Zeus Web Server version Documentation Conventions This document uses the following conventions: Item Convention Example Names of windows and name Click the Apply changes button buttons. A new term, that is new term generate a private key being defined. A variable item variable type An active URL URL Further Information For further information about running Zeus Web Server that is not covered here, please refer to our support web site, at which 24 Overview

27 provides an extensive FAQ, a range of product documentation and white papers, and access to our external mailing lists. If you are unable to find what you are looking for on this web site, or if you would like guidance in developing Zeus Web Server applications, please contact us at support@zeus.com, quoting your customer reference number in the subject header of your . Overview 25

28 26 Overview Zeus Web Server 4.3 User Guide

29 CHAPTER 2 Basic Concepts 2.1 Introduction This chapter introduces fundamental web server concepts and describes the functionality that Zeus Web Server provides. Read this chapter if you are unfamiliar with web server functionality or if you would like to read an overview of Zeus Web Server functionality. 2.2 Web Servers Introducing Web Servers In the simplest terms, web servers host web sites. One web server can host a number of different web sites: each web site is identified by an address that is used to access it. The web server makes pages available on the web by listening on the network for incoming requests for specific IP addresses, ports and host names. The web site content is stored in a directory structure within the document root (or docroot) directory. The pages are either written and stored in their entirety, or can be dynamically generated. This is described in more detail in the following section. Users access web sites using web browsers. Browsers request pages from the web server using URLs 1, such as and then display the pages returned by the server. Web servers can also receive information Basic Concepts 27

30 back from browsers, for example, when someone fills in and submits a form. They can process this information in different ways and return further pages if required. Servers and browsers communicate with each other using the Hypertext Transfer Protocol (HTTP). Web Server Functionality Web servers host web sites, which can be thought of as being made up of two types of content: Static content is content that is stored in a file (such as an HTML page, or graphic image and so on) and sent to the browser to be displayed when requested. The content does not change unless someone modifies the file. Static files are generally created and then saved in the web site document root, so that they are ideally suited to being served up from a centralized file server. For example, a movie review could be a page made up of static content. Dynamic content needs to be generated in some way before the web server returns it to the browser. Dynamic content is therefore generated on-the-fly, when requested, by calling a program that is run to produce the required output. Pages that contain dynamic content place servers under a heavier load and should be generated and served by fast machines. There are many different ways of generating dynamic content, such as CGI, FastCGI, Java servlets, and NSAPI and ISAPI applications. For example, a cinema listings page that returns the listings for a specified day could contain dynamic content. In this case the web server could query a database and build the result into a page before sending this page to the browser. Web servers handle requests for information by locating and returning any static content files, and by calling the appropriate applications to generate dynamic content. Web servers can then incorporate all this information into the response that they return to the browser. 1. For more information about URLs, refer to the World Wide Web Consortium (W3C) web site, at 28 Basic Concepts

31 In order to be able to generate and return information securely and correctly, web servers also need to be able to control access to different applications and files, and display appropriate pages or information if the requested information does not exist, or cannot be accessed by the user making the request. It is also helpful to users if web servers can log access and activity information and be configured to manage the bandwidth available to different web sites, so that users can monitor and manage their web sites effectively. Zeus Web Server Functionality Zeus Web Server is a high performance, HTTP/1.1 compliant web server with a scalable architecture that can host tens of thousands of web sites on a single machine 2. It provides distributed content generation and authentication, with comprehensive access control and supports the industry-standard APIs listed in API Support and Integration on page 20. Its functionality is described in more detail in the sections that follow. 2.3 Virtual Servers Introducing Virtual Servers A Virtual Server can be thought of as the environment that provides web server functionality for an associated web site 3. Each Virtual Server can be configured to provide a specific level of functionality, such as the ability to run CGI scripts or ISAPI applications. It has its own unique address and document root that contains the content for its web site. 2. Note that some web servers host thousands of web sites, and some large web sites are hosted by hundreds of web servers. 3. If the Virtual Server supports Subservers, as described in Subservers on page 32, then it provides the environment for a set of web sites. Basic Concepts 29

32 Types of Virtual Servers There are two different types of Virtual Server. The original version of the HTTP specification 4 associated each web site with a single IP address. This meant that as additional web sites were added to a machine, more IP addresses also had to be added, which wasn't sustainable (as there are a fixed number of IP addresses available), and limited web server scalability. These Virtual Servers are referred to as hard Virtual Servers, which means that they are identified by a unique IP address and port combination. To avoid these problems, HTTP/1.1 5 added a new way of identifying the destination web site using first the IP address and port combination, and then the contents of a Host Header (set to the requested host name). This enables one machine (with one IP address) to support multiple web sites, each of which is uniquely identified on that machine by its Host Header. These Virtual Servers are called soft Virtual Servers. A group of soft Virtual Servers can share a common IP address and port combination, and are distinguished using the Host Header field. This means that many web sites can be hosted on just one machine, without needing to configure it with many IP addresses. This is the most commonly used type of Virtual Server. Zeus Web Server supports both hard and soft Virtual Servers. It can support thousands of hard Virtual Servers (limited only by the operating system TCP stack) and tens of thousands of soft Virtual Servers (limited only by the amount of available memory and Operating System scalability and not by the Zeus Web Server software). Managing Virtual Servers using Zeus Web Server You can use Zeus Web Server to set up, run and manage multiple Virtual Servers, each of which can be configured and controlled completely independently from the others. They can be stopped and started without affecting any others, and can also be monitored independently (described in Monitoring Activity on page 38). 4. HTTP/0.9, defined in 5. The HTTP/1.1 RFC can be found at 30 Basic Concepts

33 i Each Virtual Server can have individual bandwidth limits specified (as described in more detail in Bandwidth Throttling on page 34), ensuring that no one Virtual Server can use more than its share of system resources. This can help guarantee particular levels of service for each Virtual Server, and also help contain any denial of service attacks. Note: Because SSL security is configured for particular IP address and port combinations, this means that hard Virtual Servers can be configured independently with SSL security, but soft Virtual Servers cannot. Refer to Creating a New Virtual Server on page 45 to find out how to create a new Virtual Server using Zeus Web Server. 2.4 Clusters Introducing Clusters A cluster is a group of computers, each of which is running the same set of Virtual Servers (with the same configurations). This means that they are effectively hosting their web sites across multiple machines, so that they act together like one big web server, commonly called a web server farm. Clusters are usually run in conjunction with some sort of intelligent load balancing mechanism that distributes incoming web requests across the web servers in the cluster. This can be used to ensure that the web servers are loaded evenly, and that no particular web server is overloaded with requests, particularly if other web servers have spare capacity available. It can also mean that if one machine fails then its load is shared transparently between the others, thus providing fault tolerance. There are a number of different load balancing solutions available, implemented both in hardware and software, including Zeus Load Balancer For more information about Zeus Load Balancer, refer to Basic Concepts 31

34 Clusters enable you to increase your web serving computing power easily by simply adding more computers to the cluster. This can often be cheaper and involve less downtime than upgrading a single central server. You can also store your static web pages using a centralized networked file system (NFS) that can be accessed by all machines in the cluster. Managing Clusters with Zeus Web Server Zeus Web Server makes it as simple and straightforward to set up and manage multiple web sites on a cluster of web servers as it is to set them up on just one. The Administration Server manages and coordinates all the web serving components within the system (which can also include other products such as Zeus Load Balancer 6 ). It holds the master configuration for all the web servers in the cluster, and automatically updates their configuration at the same time, thus ensuring consistency across the cluster. This means that you can deploy web site configurations across the entire cluster at the click of a button, and can monitor the real-time activity of the cluster. Zeus Web Server clusters therefore provide an easy way of hosting multiple web sites across multiple machines, so that you can easily add machines as required, and eliminate single points of failure in your web hosting network. Refer to Creating a Cluster of Web Servers on page 284 for more information about setting up a cluster using Zeus Web Server. 2.5 Subservers Introducing Subservers Hosting providers often want to be able to run many web sites with similar configurations. For example, they might want to be able to offer a small set of service offerings (levels of web site functionality) with an associated pricing system, and an easy way of moving customers between them. Subservers provide an easy way of configuring, managing, supporting and scaling lots of similarly configured web sites. They enable you to set up the web site functionality just once, in just one place (the Virtual Server), and then use it to support a large number of separate web sites. This type of 32 Basic Concepts

35 Virtual Server has multiple document roots, each of which is accessed as a separate web site. Each of these document roots is associated with its own Host Header, and is called a Subserver. Subservers make it simple to set up multiple web sites configured with the same functionality whilst avoiding the memory and disk usage overheads of running hundreds of Virtual Servers. They can be configured and managed easily just by configuring and managing one Virtual Server. Managing Subservers using Zeus Web Server Zeus Web Server enables you to set up Subservers by simply creating a Virtual Server with Subserver functionality enabled. You can then add Subservers to the Virtual Server simply by adding subdirectories to the Virtual Server document root 7 : you do not need to configure any other information or stop and start the Virtual Server. This means that adding a new web site can be as easy as simply creating a new directory. Each of these Subservers supports the functionality provided by their hosting Virtual Server. When the Virtual Server receives a request for a Subserver, it simply checks to see whether it has a document root directory of the same name as the request s Host Header. If so, it returns the appropriate file from that document root. Customers can simply be given access to a Subserver document root (providing them with whatever functionality the associated Virtual Server is configured with), and they can then maintain and update their web sites in the usual way. 7. Because operating systems usually provide a limit to the number of subdirectories that can be supported within a directory (and therefore to the number of document root directories that can be supported), the Zeus Web Server uses a hashing scheme that extends this and enables approximately 70 billion (2 36 ) document root directories or Subservers to be supported on one Virtual Server. This means that in practice other limits constrain the total number of document roots. Basic Concepts 33

36 2.6 Bandwidth Throttling Bandwidth throttling enables you to limit the bandwidth available to any given web site. It can be used to ensure that no single web site uses all the available bandwidth, thus compromising the availability of other web sites hosted by the same web server. Zeus Web Server makes it easy for you to specify the bandwidth that is available to each Virtual Server (or Subserver), as described in Configuring Bandwidth Throttling on page Web Server Security Introducing Web Server Security Web server security is made up of a number of different aspects. To be secure, web servers cannot simply send pages straight to clients (browsers) in a form that can be intercepted and read by anybody. Web servers must be able to ensure that only the client that is supposed to be reading (or editing) something is able to do so. This enables sensitive information such as names, addresses and credit card numbers to be transmitted securely between web servers and web browsers. The table below summarizes the different aspects of web server security and how these issues can be solved using a particular security implementation, called SSL (Secure Sockets Layer) security: Aspect Issue Solution Identity Are you really talking to the person or web site that you think you are? Web servers authenticate themselves to browsers using public and private keys, and certificates. 34 Basic Concepts

37 Aspect Issue Solution Privacy Is anyone else reading the information you are sending or receiving? Web servers agree an Encryption Key with the browser and use it to encrypt all information they send. Integrity Are you reading what was actually sent to you, or has it been modified in transit? Introducing Private Keys The first step in configuring web site security is to generate a private key. This key is used to unlock the coded communication that is intended only for the key holder. Introducing Signed Certificates Signed certificates are certificates that are signed by a recognized Certificate Authority (CA), such as VeriSign, vouching for your identity. If you are going to use a publicly-recognized signed certificate, you will need to purchase one from a recognized CA who will use the information that you provide to check that you are who you say you are. Once you have received your requested public certificate from the CA, you need to configure your Virtual Server to use it. Introducing Self-Signed Certificates While waiting for a signed certificate, you can generate a self-signed certificate that you can use for web site security testing. A self-signed certificate simply states that you are who you say you are, without any independent verification. Note that it is not necessary to do this; you can use a signed certificate, without having used a self-signed certificate, but it does enable you to develop and test your system first. Zeus Web Server Security Support Web servers send each encrypted message with a Message Authentication Code. Zeus Web Server provides full support for 128 bit SSL v3 and client-side X.509 certificates. It also supports hardware crypto-accelerators that can be used to Basic Concepts 35

38 carry out the SSL processing in hardware, and so reduce the load on the machines running the web servers 8. The Zeus Web Server interface makes it extremely easy to set up SSL-enabled web sites. It can generate private keys, self-signed certificates and certificate signing requests that can be sent to a recognized CA. It is integrated with the VeriSign web site, and can lead you through the process of buying a signed certificate. It also provides clustered support for SSL, so that you can set up SSL-secured web sites across a cluster. For more information about setting up SSL, refer to Setting up Virtual Server SSL Security on page Note that most of the SSL processing overhead occurs when the secure connection to the Virtual Server is being established. Once established, an SSL connection uses little additional load. 36 Basic Concepts

39 2.8 Logging Logging enables you to record information about your web server system. Zeus Web Server can record the following types of information: Error logs record information about Zeus Web Server s activity. These logs are categorized in the following way: Information Type Marked Indicates Status information INFO Normal web server activity. For example, the web server starts and stops. Warning information WARN There was a problem starting a resource such as a Virtual Server, but it has still been started. For example, the specified global.htaccess file could not be found, and so the Virtual Server was started without it. Error information SERIOUS There was a problem starting a resource such as a Virtual Server, that prevented it from starting. For example, a Virtual Server s document root could not be found. Fatal information FATAL There was a problem that prevented the product from running. For example, an installation file has been corrupted and so Zeus Web Server is unable to run. Request logs record information about every request received by each Virtual Server. You can specify exactly what information is logged, and use these logs in conjunction with the Traffic History pages (introduced in the following section) to provide the basis for detailed analysis of your web site usage trends. Zeus Web Server enables you to switch request logging on and off, specify where the logs are written to and configure which fields are included in the logs (on a per-virtual Server basis), so that you can include exactly the information that you need and no more. For more information about configuring logging, refer to Configuring Request logging on page 165 and Error Handling on page 173. Basic Concepts 37

40 2.9 Monitoring Activity Zeus Web Server enables you to monitor your web server activity in the following ways: Real-Time Monitoring This page displays real-time statistics that enable you to monitor the activity of the web servers on any of the machines in your cluster. It displays a real-time graph, that can be updated every second, showing how often various events occur within Zeus Web Server. You can monitor a wide range of events, such as how many requests the web server is answering, how many times a specific HTTP error page is returned, or how often a particular piece of functionality is used. Refer to Real-Time Monitoring on page 73. Traffic History These pages 9 display dynamically-generated graphical information about web site activity (the hits or bytes transferred from each web site over the previous day or week). These pages display graphs showing recent activity for the selected categories of information (such as machines or Virtual Servers and so on). Refer to Using the Traffic History Pages on page 78 for more information about using this. Note that this activity information is held separately from the request and error logs (introduced in the previous section) Script-Based Management Zeus Web Server provides an easy-to-use web-based interface for configuration, management and administration tasks, which calls a set of underlying scripts. Sometimes, however, a task may need to be repeated hundreds of times, say. In this case it can be easier to simply run the scripts directly from the command line, or combine multiple commands in a script of your own. This can be helpful if you are performing repetitive tasks, or are performing a complex task made up of many individual small steps. 9. Previously known as the Activity Monitor 38 Basic Concepts

41 For more information about using scripts and manipulating configuration files, refer to Scripting Overview on page 369. Basic Concepts 39

42 40 Basic Concepts

43 CHAPTER 3 Starting Zeus Web Server 3.1 Introduction This chapter assumes that you have installed Zeus Web Server, as described in Zeus Web Server Getting Started Guide. It describes how to start Zeus Web Server, how to access its user interface pages and how to create a Virtual Server. Read this chapter if you are running Zeus Web Server for the first time. The next chapter describes how to configure your Virtual Servers. 3.2 Starting and Stopping Zeus Web Server Starting Zeus Web Server Normally Zeus Web Server starts automatically once you have installed it. To access it follow the instructions in the next section. If, for any reason, however, Zeus Web Server has not started, you can start it explicitly by entering the following command, as the user that you installed under (usually root): $ installation_dir/start-zeus Where installation_dir is the directory that you installed in. Starting Zeus Web Server 41

44 Stopping Zeus Web Server Similarly, you can stop Zeus Web Server from the command line as the user that you installed under (usually root) in the following way: $ installation_dir/stop-zeus! Where installation_dir is the directory that you installed in. This stops all the Virtual Servers on Zeus Web Server. Warning: Once you have stopped Zeus Web Server, you will no longer be able to access the user interface pages, or any of its Virtual Servers or the web sites that they are running. Starting and Stopping Individual Components The start-zeus and stop-zeus commands start and stop all the installed components. These include the administration component, which enables you to access the user interface pages, and the web server component, which runs all the Virtual Servers. If you have other Zeus products installed there will be other components too. You may want to leave the web server component running, and just start the administration component when you want to access the user interface pages. In this case you can start the administration component in the following way: $ installation_dir/admin/rc start To stop the administration component, do the following: $ installation_dir/admin/rc stop 42 Starting Zeus Web Server

45 3.3 Setting Up your Browser and Reader This section describes some of the browser and PDF reader settings that you can specify in order to maximize the functionality of the User Interface. Multiple Language Support The user interface pages can be displayed in any of the languages that are available as a Zeus Web Server language pack. To display them in one of these languages, simply configure that language as your preferred language in your browser settings. These can typically be found in the browser s options or preferences menu. Viewing the Virtual Server tree structure It is recommended that you enable cookie support in your browser. This enables the expanded state of your Virtual Server tree to persist as you move between pages. All the functionality will still work if you do not enable cookie support but you may find that you need to keep expanding your Virtual Server tree every time you access the Virtual Server Status page. Viewing the online documentation The online documentation is displayed using the Adobe Acrobat reader 10. It is recommended that you set your Adobe Acrobat reader settings to display in continuous mode. Do this by accessing the Adobe File/Preferences/General dialog box. Set Default Page Layout to Continuous. 3.4 Accessing the Zeus Web Server Interface Pages To access the Zeus Web Server interface pages, enter the URL that was returned to you during the installation process (as described in the Zeus Web Server Getting Started Guide) in your browser location bar. This usually has the form: where yourmachinename is the name of the machine on which you installed Zeus Web Server, and AdminServerPort indicates the port that it is running on (usually port 9090) This can be downloaded free of charge from Starting Zeus Web Server 43

46 Your browser displays the login dialog box: Enter admin into the User Name field, and enter the password that you chose during the installation process into the password field. Note that both of these fields are case-sensitive. Zeus Web Server displays an empty Virtual Server Status page: 11. This information is also logged in the Administration Server log file, that can be found in installation_dir/admin/log/errors. 44 Starting Zeus Web Server

47 i Note: You can bookmark this page, so that it is easy to return to. This page provides access to the Virtual Server management and configuration pages for controlling your Virtual Servers. Note that if you install other Zeus products, the page also displays links to their associated management and configuration pages. The next step is to create a Virtual Server, as described in Creating a New Virtual Server on page 45. For more information about using this page, refer to Basic Tasks on page Preparing to Publish a Web Site Before setting up your first Virtual Server and publishing a web site, you should have the following: An address for the web site, that visitors will use to access it. You will need to register the domain name, and then set up a DNS entry for it before using it. For example, to set up the web site register the mywebsite.com domain name and then set the DNS entry for to your Zeus Web Server computer s IP address. The web pages, associated files, and applications that provide the content for your web site. 3.6 Creating a New Virtual Server The first step in using Zeus Web Server is to create at least one Virtual Server. A Virtual Server hosts web site content and provides the functionality used to generate its dynamic component. Virtual Servers are described in more detail in Virtual Servers on page 29. Starting Zeus Web Server 45

48 To create a new Virtual Server, simply do the following: 1) Click the Virtual Server link in the Web Controller menu. Zeus Web Server displays the Create a New Virtual Server page: 46 Starting Zeus Web Server

49 2) Fill in the fields on this page in the following way: Set this field... Virtual Server Name Host Name and Port Server Comment Document Root... to... a name that will help you identify this Virtual Server easily. It can contain letters, numbers, hyphens, dots and underscores, but no spaces a (for example, personal, secure, or ). It also cannot start with an underscore. Zeus Web Server uses this name to identify this Virtual Server to you in the Virtual Server Status page, but it will not be seen by people viewing and using its web site. the URL that clients will use to visit the Virtual Server s web sites. It can be made up of letters, numbers, hyphens (-) or dots (.), but no spaces or underscores. You must ensure that you have registered this domain name and set up a DNS entry for it, as described in Preparing to Publish a Web Site on page 45. Note that you should also include the port number that the web site is running on if this is anything other than the default HTTP port (port 80). This will not normally be the case, but might be useful for you to do if you are developing and testing a new web site b. comments about the Virtual Server. This text is displayed in the Virtual Server Status page, so you can use it to record any information that you want to associate with the Virtual Server. the full name and path of the subdirectory in which you are storing the Virtual Server s web site content. Note that this is the full path and so must start with a /. Starting Zeus Web Server 47

50 Set this field... Aliases... to... specify aliases for your web site. Virtual Server aliases are a way of specifying alternative web addresses for a web site: the user goes to the same web site, and sees the same web pages, whichever alias is used. It can be helpful to specify a number of alternative addresses that you think users might use to access your web site. For example, you could specify to be an alias for c Specifying an alias of * means that this Virtual Server will be treated as the default Virtual Server for the IP addresses that it is binding to. This means that the Virtual Server will process requests for any host headers that do not match any configured aliases or host names for these IP addresses. Do not configure more than one Virtual Server with an alias of * on any IP address. You can also configure a Virtual Server to respond to a number of web sites within a domain. For example you could specify *.accounts.mybank.com and *.mybank.co.uk, so this Virtual Server will serve products.mybank.co.uk and platinum.accounts.mybank.com. You can only use * for a wildcard as the first character of the alias. It is not possible to specify Note that in the same way that you must register a domain name before using it as a web site address, you must also register any domain names that you wish to specify as aliases. Note that this field can only be specified for Soft Virtual Servers. 48 Starting Zeus Web Server

51 Set this field... Webmaster address Clone server... to... the address of the person responsible for this web site. Zeus Web Server automatically includes this address in its default error web pages d. This enables people viewing your web site to report any problems more easily. If you do not specify an address then Zeus Web Server uses (where web_site_address is your host name with any leading www. removed). the name of another Virtual Server on which to base this one (if any). Either accept the default configuration settings by leaving the drop down box set to [skeleton config], or, if you already have a Virtual Server that is set up differently, then you can select its name to specify that these settings should be copied instead. Note that the drop down box is not displayed if you have a very large number of Virtual Servers. In this case you should enter the name of the Virtual Server in the field instead. a. The Virtual Server Name is used as the name of its configuration file. b. Note that if you are running Zeus Web Server as a non-root user, you will only be able use ports greater than c. Users using an alias to access your web site will continue to see that alias displayed in their browser location bar. Aliases are not the same as HTTP redirection, in which users accessing one web site are automatically redirected to another (whose web site address is then displayed in their browser location bar). d. For information about changing the default HTTP error pages, refer to Customizing HTTP Error Pages on page ) Click the Create Virtual Server button.! Zeus Web Server creates a new Virtual Server and adds it to the tree displayed on its Virtual Server Status page, and displays its configuration pages (described in Using the Configuration Pages on page 89). Warning: If you are already running one web server (perhaps because you are evaluating Zeus Web Server beside an existing web server), then you must ensure that you specify a port (other than port 80) in the Host Name and Port section. Starting Zeus Web Server 49

52 This is because the existing web server is already listening to port 80 and so your Zeus Web Server Virtual Servers must be associated with a different port. 3.7 Using the Virtual Server Status Page The Virtual Server status page displays all your Virtual Servers and their current status. It enables you to create new Virtual Servers, and to monitor and manage them. This section describes the page layout and how to use this page. Border bar Main Screen Area Web Controller menu Button Set Overview of the Virtual Server Status Page Layout The Virtual Server status page contains the following: Main Screen area The main screen area displays a tree of your configured Virtual Servers, 50 Starting Zeus Web Server

53 ordered by Virtual Server name. Virtual Servers can be grouped together, as described in Grouping Virtual Servers on page 56. Each Virtual Server is displayed with its name and its web site URL. When the Virtual Server is running, the URL (usually 12 ) provides a hyperlink to the Virtual Server s web site. Each Virtual Server is also displayed with the following set of status icons: Icon Name Icon... indicates that... Running State Icon the Virtual Server is running. the Virtual Server was not started successfully. Click the Diagnose icon for further information about the problem. the Virtual Server is stopped. Configuration Changes Icon the Virtual Server was not stopped successfully. Click the Diagnose icon for further information about the problem. the Virtual Server s configuration has changed but the changes have not yet been committed. See Committing Configuration Changes on page 61 for more information. Other Icons To view details about a problem, click the Diagnose icon: To edit a Virtual Server, click the Configure icon: Button Set The buttons under the Virtual Server tree enable you to carry out actions on the selected Virtual Servers. Web Controller menu The Web Controller menu provides links for creating Virtual Servers and 12. There is no hyperlink if the Virtual Server has the Subserver functionality set (see Configuring Subservers on page 253). Starting Zeus Web Server 51

54 groups of Virtual Servers. It also provides the Find VS field, described in Searching for a Virtual Server on page 59. Border bar The border bar provides the following buttons: Button Name Use it to... Documentation... view the online documentation. Home... return to the Virtual Server Status page. Starting and Stopping a Virtual Server Virtual Servers can be running or stopped. A running virtual server can receive and process traffic; a stopped virtual server does not, and uses no resources on the web server. When you create a new virtual server, it is not running. You must start it when you want it to be active. To start a virtual server, select the virtual server from the list in the Main Screen Area. Then, click the Start button in the Button Set. To stop a virtual server, select the virtual server from the list in the Main Screen Area and click the Stop button in the Button Set. Committing Configuration Changes The configuration settings that a virtual server is using (whether it is running or not) are referred to as the Committed Configuration. If you start or restart a virtual server, it will use the committed configuration settings. When you make configuration changes using the Administration Server, they do not take effect immediately. Once you have made your changes, which may involve editing several different parts of the configuration, you can then review and commit them. 52 Starting Zeus Web Server

55 You will see a yellow star icon light up in the Administration Server if you have uncommitted changes, and you will receive a warning each time you make a change. To commit your changes, click on the yellow star or on the warning text. This will take you to a page where you can review your changes, and choose either to commit them or to revert them back to the previously committed configuration. Committed changes take effect immediately on a running virtual server. On a stopped virtual server, they take effect when the virtual server is next started. 3.8 Publishing a Web Site In order to publish a web site on a Virtual Server, do the following: Put your pages and any associated files and programs into a directory structure under the Virtual Server document root 13. Ensure that the Virtual Server is running as described in Starting and Stopping Virtual Servers on page Viewing Your Web Site When the Virtual Server is running, you can click the web site address link to view its web site 14. Your browser then displays the Virtual Server s home page in a new window. As long as the web site s Virtual Server displays a green Running State icon (indicating that it was started successfully and is running), users can access it. 13. You can also put content into any directories that you have mapped to the document root directory structure using the URL mapping functionality (refer to Configuring URL Mapping on page 126 for more information). 14. If the Virtual Server supports Subservers, however, no active link is displayed here. Starting Zeus Web Server 53

56 You can now maintain and update the web site in the following ways: You can edit the files in its document root. You can modify its configuration as described in Using the Configuration Pages on page 89. You can monitor it using the Traffic History pages (as described in Using the Traffic History Pages on page 78). You can analyze its traffic by parsing the log files (see Configuring Request logging on page 165 and Error Handling on page 173). 54 Starting Zeus Web Server

57 CHAPTER 4 Basic Tasks 4.1 Introduction This chapter describes how to use Zeus Web Server to carry out basic tasks. It assumes that you have read Starting Zeus Web Server on page 41 and that you have already created your first Virtual Server, as described in Creating a New Virtual Server on page 45. It describes how to modify, monitor and manage multiple Virtual Servers and how to set up secure communication for them. It also describes how to configure your preferences and administration security settings. 4.2 Configuring Virtual Servers Zeus Web Server enables you to modify the configuration for one or more Virtual Servers easily, as described in the following sections. Configuring One Virtual Server Once you have created a Virtual Server, you can view and modify its configuration in one of the following ways: Click the Virtual Server's Configure icon:. Click its check box and click the Configure button at the bottom of the page. Basic Tasks 55

58 This takes you to the Virtual Server's configuration pages, described in Using the Configuration Pages on page 89. Modifying Multiple Virtual Servers You can configure multiple Virtual Servers at once in order to configure the functionality consistently across them all. The configuration pages then enable you to make individual settings consistent across all Virtual Servers or, if set differently, to leave them as they are. Do this in the following way: 1) Select multiple Virtual Servers by clicking their check boxes. 2) Edit their configuration by clicking the Configure button at the bottom of the page. This takes you to the Virtual Server's configuration pages, described in Using the Configuration Pages on page 89. Alternatively, you can group multiple Virtual Servers together, as described in the next section, and edit the group. 4.3 Grouping Virtual Servers Groups are a way of labeling a number of Virtual Servers, and displaying them next to each other so that you can monitor and configure them together easily. Groups are useful for labelling Virtual Servers that are configured consistently across particular configuration items and so it is helpful to use a descriptive group name. For example, you could create a group of FastCGI enabled Virtual Servers, called FastCGI Group or create a group with consistent MIME types, called MIME Group. i Note: Putting a Virtual Server into a group does not in itself change the Virtual Server configuration in any way - but it can help you label and manage common functionality within your set of Virtual Servers. 56 Basic Tasks

59 Creating a Group To create a group, click the Group link on the Web Controller menu. The Create New Virtual Server Group page displays all your Virtual Servers: Create a new group in the following way: 1) Accept the default group name or specify a new one in the Group name field. This is a name that will help you identify this Virtual Server group easily. It can contain letters, numbers, hyphens and underscores, but cannot contain spaces or start with an underscore. Zeus Web Server uses this name to identify this Virtual Server group to you in the Virtual Server Status page, 2) Enter some descriptive text about the group in the Group comment field. It is recommended that you use this to record information about the group, so that it is easy to remember why you created the group. Basic Tasks 57

60 i 3) Select the Virtual Servers (or groups) that you want to place in the group by clicking the check box beside each. 4) Click the Set Group Name, comment and members button. Zeus Web Server creates the group, and displays the Virtual Server status page with the new group highlighted (in green) and selected. Note: You can add an individual Virtual Server to multiple groups: it is then displayed as a member of each. However if a Virtual Server is in multiple groups then this may make it hard to maintain consistency across the groups (as you may be trying to make the same configuration item consistent in different ways across each of the groups). To see which groups a Virtual Server belongs to, select it and view its configuration summary page (see Viewing the Configuration Summary on page 96). Note that this group membership information is not displayed when multiple Virtual Servers are selected. For further information about using groups refer to the following: Changing the Members of a Group on page 58 Adding Virtual Servers to an Existing Group on page 59. Deleting Groups on page 65. Changing the Members of a Group To change which members are in a group, click the group name in the Virtual Server tree. Zeus Web Server displays the Modify Virtual Server Group page with the Virtual Server tree. The current members of the group are selected in the tree. To modify the group name, simply edit the Group name field. To add and remove group members, select or deselect the members in the tree. Click the Set group button to update the group. 58 Basic Tasks

61 For information about deleting the members from a group refer to Deleting Groups on page 65. Adding Virtual Servers to an Existing Group Add new members to a group by creating a new Virtual Server, based on an existing member of the group. To do this, use the Clone Server option on the Create a New Virtual Server page. This creates a new Virtual Server with the same configuration as the one that you based it on. You can then configure individual items differently. Configuring a Group To edit the configuration of all the members of a group you simply click the group's configure icon or select its check box and click the Configure button at the bottom of the Virtual Server Status page. Searching for a Virtual Server You can search on Virtual Servers by name. Enter the literal string (with no wildcards) in the field in the Web Controller menu and click the Find VS button. The Virtual Server status page highlights (in green) all the Virtual Servers whose names contain the specified text, and expands the tree to show them. 4.4 Monitoring Virtual Servers and Groups The Virtual Server status page displays the real-time status of your Virtual Servers and groups so that you can monitor them as described in the following sections. Basic Tasks 59

62 Monitoring Virtual Servers Virtual Servers are displayed with one or more of the following icons: Icon Name Icon... indicates that... Running State Icon the Virtual Server is running. the Virtual Server was not started successfully. Click the Diagnose icon for further information about the problem. the Virtual Server is stopped. Configuration Changes Icon the Virtual Server was not stopped successfully. Click the Diagnose icon for further information about the problem. the Virtual Server s configuration has changed but the changes have not yet been committed. See Committing Configuration Changes on page 61 for more information. 60 Basic Tasks

63 Monitoring Groups Groups are displayed with one or more of the following icons: Icon Name Icon... indicates that... Running State Icon Configuration Changes Icon the group is running - all of the Virtual Servers in the group are running all the Virtual Servers in the group failed to start successfully. Click the Diagnose icon for further information about the problem the group is stopped - all of the Virtual Servers in the group are stopped all the Virtual Servers in the group failed to stop successfully. Click the Diagnose icon for further information about the problem some of the group s Virtual Servers are running, and some are stopped the group contains at least one Virtual Server that was unable to start or stop successfully. Note that this means that if this is the case for any Virtual Server, then the all group will be displayed in this way. This can be helpful for alerting you to system inconsistencies. the group contains at least one Virtual Server that has a Changes icon displayed. Note that this means that if any Virtual Servers in your tree have uncommitted changes, then the Changes icon will be displayed beside the all group. This can be helpful for alerting you to uncommitted changes. See Committing Configuration Changes on page 61 for more information. 4.5 Committing Configuration Changes The committed configuration is the one that the Virtual Server is running. The current configuration (the one that you are editing) may not be the same as Basic Tasks 61

64 i! the committed one. The edited configuration becomes the committed configuration when you commit it, and the Virtual Servers are updated to start using it. Note: In version 3 of Zeus Web Server it was necessary to stop and restart a Virtual Server in order to update its configuration. (Conversely, the configuration was automatically updated whenever you started a Virtual Server.) There is now a separate explicit commit configuration changes step that provides you with more configuration control and enables you to bundle up multiple changes and commit them at one time. Committed changes are applied immediately to all running Virtual Servers, and are applied to any Virtual Servers that are stopped the next time that the Virtual Server is started. Warning: When you commit changes to a Virtual Server you lose all current connections to any of its web sites. This is because when configuration changes are committed to a running Virtual Server, the Virtual Server is automatically stopped and restarted. This means that although you no longer need to explicitly stop and restart it, you should be aware that this still happens. When the Configuration Changes icon is displayed, this indicates that the edited configuration(s) have changes that have not been committed to the running configuration(s). 1) Click the Configuration Changes icon to see a page that summarizes the changes between the edited ( new ) configuration and the most recently committed configuration (that is, the changes that you are about to commit to the running configuration). The Summary View lists the number of changes made on each configuration page, with a link to each. To view detailed information click the Show detailed view link at the end of the table. The Detailed View lists each of the configuration keys that has changed with its existing committed value and its new (edited) value. Use this view only if you are familiar with configuration keys. To return to the summary view, click the Show summary view link at the end of the table. 62 Basic Tasks

65 2) Do one of the following: Click the Commit button to commit the edited configuration to the selected Virtual Servers. Click the Revert button to discard these changes, and revert to the previously committed configuration. 4.6 Starting and Stopping Virtual Servers i To start one or more Virtual Servers, select them and click the Start button 15. Zeus Web Server updates the Running State Icon of each, and each Virtual Server's web site becomes available, and displayed as an active link. If Zeus Web Server detects any errors, it displays them in a text box at the top of the Virtual Server Status page. Note: Starting a Virtual Server does not automatically update its configuration. The configuration is only updated when you commit it, as described in Committing Configuration Changes on page 61. This enables you to have greater control over when you update your running configurations. To stop one or more Virtual Servers, select them and then click the Stop button. Zeus Web Server updates the status of each. 4.7 Resolving Problems Using the Diagnose Icon A Running State icon with an attention indicator indicates that the group or Virtual Server could not be started or stopped successfully 16. This is either because of a configuration problem or because the Administration Server is unable to contact the machine(s) on which the Virtual Server is supposed to 15. To start an individual Virtual Server you can also click its Running State Icon if you have set up your preferences appropriately. This is described in Configuring your Preferences on page Specifically, it indicates that the Virtual Server s desired running state does not match its actual state. Basic Tasks 63

66 be running to find out whether it is running or not. This means that if a machine in a cluster goes down, or if you accidentally delete a set of configuration files from the machine in a cluster then the Virtual Server status page alerts you to this. To view details about the problem, click the Diagnose icon: Zeus Web Server displays a page that provides more information about the discrepancy and how to resolve it. Use this in the following way: 1) By default the page displays all the problems listed by each web server on every machine. To view the problems listed by Virtual Server instead, click the link at the bottom of the list. 2) You can use Zeus Web Server to fix these problems automatically in the following ways: To attempt to automatically fix selected problems, select them in the Auto-Fix column. To attempt to fix all problems on a Virtual Server, web server on a machine, or page, click the appropriate fix all errors check box. Click the Fix selected problems button. 3) Zeus Web Server attempts to fix the specified problems. If it is able to fix a problem successfully then it removes the problem from the list. If it is unable to fix a problem (if, for example, a machine needs to be started), it displays the output from the attempt in a text box above the table, and displays Auto-fix failed beside the problem. Consult the diagnostic error messages to help you fix the problem manually. If you are still unable to resolve the problem then you can contact Zeus technical support, as described in Sending a Technical Support Query on page Basic Tasks

67 4.8 Deleting Items Deleting Virtual Servers To delete one or more Virtual Servers, select them and then click the Delete button. Zeus Web Server removes them from the tree. Note that this deletes the Virtual Server's configuration files but does not delete its document root, web site content, or its SSL certificate sets (see Setting up Virtual Server SSL Security on page 68 for more information about SSL certificate sets). Deleting Groups To delete one or more groups, select them and then click the Delete selected items button. Zeus Web Server provides the following options: To delete the group and all its members, click the Delete, including contents button. To delete the group, but not its members, click the Delete groupings only button. Specify whether just the group should be removed, leaving its Virtual Servers in the tree, or whether to delete all the Virtual Servers within the group as well. 4.9 Licensing Web Server Machines You can install and run Zeus Web Server without a full license 17. You can create and configure Virtual Servers, but you cannot start them until it has been licensed. The Zeus Administration Server does not require a license key to run. 17. In version 4.1 and above. Previous versions of ZWS required you to have a valid license key before you could install and run it. Basic Tasks 65

68 Licensing Mechanisms When you install Zeus Web Server you may provide a license key if you have one. Whether you provide a key or not will determine what the product will allow you to do: If you do not provide a license key when installing, then you will be able to create and configure Virtual Servers, but you will not be allowed to start them. If you do provide a valid license key when installing, you will be able to create, configure and start Virtual Servers. There are two types of license keys: An evaluation license enables you to run Zeus Web Server for a specified period of time. Once it has expired then the key it is no longer valid. You will then need to obtain a full license in order to continue using Zeus Web Server. A full license enables you to run Zeus Web Server for an unlimited period of time. In order to start any Virtual Servers (and so make web sites available) you must have a valid license key (either a full license or a current evaluation license). You can use the Licensing Information page to obtain a license. Viewing Server License Details Each machine running a web server component in your cluster needs to be licensed individually. To view a list of the servers in your system, and see what kind of license keys they currently have, use the Licensing Information page. Access this by clicking the Licensing link in the Web Controller menu. This page lists the current license information for each server in your cluster and enables you to view and update the licenses on each server. It also shows the name of the server and the version number of Zeus Web Server which is running. To update a license simply click the Upgrade license link associated with that web server. 66 Basic Tasks

69 Instead of a license key, you may be issued with a Right-To-Use (RTU) key. This can be exchanged on the Licensing Information page for a full license key. Updating a Web Server License This page provides two actions which can be performed: Obtaining a new License Key Installing a new License Key The options available will depend on the current licensing status of the server you have selected. For example, if no license key is installed, then it is possible to obtain an Evaluation License key or purchase a full license key When you select one of these options, your admin server will send the machine architecture and network details of your server to the Zeus licensing web site. The Zeus licensing web site will then guide you through the steps needed to obtain the key. If you select Exchange an RTU key, you should copy your RTU key number into the text box, and after answering a few questions, you will be provided with a full license key. To install the new license key, you should save your license key to your local disk from your browser. Then enter the full pathname or select the Browse button and select the key to install. The new key will be checked and installed on the server. If you reload the Licensing page, the status of the server will be updated to reflect the new license key you have installed. i Note: Specifying a directory instead of a file when installing your licence key may confuse your browser and cause it to lock up. Basic Tasks 67

70 4.10 Setting up Virtual Server SSL Security Zeus Web Server enables you to set up 128 bit SSL security 18 on individual Virtual Servers. Zeus Web Server can generate the necessary SSL certificates and private key files for configuring SSL support, and provides an easy way to manage them. It can also deploy these files automatically on every machine in your cluster. To simplify setting up SSL support for individual Virtual Servers, Zeus Web Server uses SSL certificate sets. Each certificate set consists of an SSL certificate and its associated private key file. Zeus Web Server automatically generates the private key file, and leads you through the process of getting an SSL certificate signed by an external Certification Authority. Using Certificate Sets To create and manage certificate sets, use the Certificate Set Management page. Access this by clicking the SSL Certificates link in the Web Controller menu. This page enables you to: Create a new certificate set Zeus Web Server enables you to create certificate sets, automatically generating a private key and an SSL certificate. For more information, see Creating a Certificate Set on page 69. Import existing files into a certificate set. Use this to create a certificate set from any existing private keys and SSL certificates. Do this to enable Zeus Web Server to manage them for you, and automatically deploy them on all the machines in your cluster. For 18.For more information about SSL, refer to the Zeus white paper, SSL: Theory and Practice, which can be found in Documentation and Whitepapers at: 68 Basic Tasks

71 further information, see Importing Existing Files into a Certificate Set on page 71. View the currently configured certificate sets The page displays a table of existing certificate sets, and enables you to configure them. Initially there are no certificate sets defined. For more information about this, see Managing Certificate Sets on page 71. Creating a Certificate Set Before you can use SSL security on a Virtual Server you must create a certificate set, composed of a private key and an SSL certificate. Zeus Web Server generates the private key file for you, and enables you to select which type of SSL certificate to create, from the following: A self-signed certificate Self-signed certificates are simple and fast to create, but are only useful for security testing on your system, and should not be used for live web sites. If you use a self-signed certificate to secure your web site, visitors may see a warning when they first view the web pages, because the certificate has not been signed by a recognized Certificate Authority (CA). Users will need to accept the certificate to continue viewing the web site. If you create a self-signed certificate, you can upgrade it to a signed certificate later. For information on how to do this, see Issuing a Certificate Signing Request on page 72. A certificate signed by VeriSign Certificates signed by VeriSign can be used to implement SSL security on live web sites. Zeus Web Server leads you through the process of requesting a signed certificate from the VeriSign web site. Once the request has been made, you may have to wait several days before receiving the certificate. Note that VeriSign charge for this service. A certificate signed by another Certification Authority Signed certificates, suitable for implementing SSL security on live web sites, can be obtained from a number of Certification Authorities other than VeriSign. Zeus Web Server enables you to generate a Certificate Signing Request to send to the Certification Authority, and then process Basic Tasks 69

72 the response you receive. For further details, see Issuing a Certificate Signing Request on page 72. To create a certificate set, do the following: 1) On the Certificate Set Management page, click the Create button. 2) Choose whether you want to create a self-signed certificate, or one signed by a CA, by clicking the appropriate radio button, then click the OK button. 3) Enter the required SSL certificate information, as described in Entering Certificate Set Information on page 70, and follow the on-screen prompts to complete the process. The new certificate set appears in the list of certificate sets on the certificate set management page. Entering Certificate Set Information When creating a certificate set, enter the following information: The certificate set name. This is used within Zeus Web Server to refer to the certificate set. The name must be unique, and can contain letters, numbers, hyphens, dots and underscores, but no spaces. It also cannot start with an underscore. The web site name. This is the name of the web site that this certificate is registered to. Enter just the host name, without any directories, for example, The name of your organization. This is the full legal name of your company or organization, and should not contain abbreviations except Inc., Corp., and so on. Your organizational unit. This optional field identifies your department within your organization. Your location. This is the full name of your town or city. Your state or province. This field is optional if you are located outside the United States. 70 Basic Tasks

73 Your country. This must be entered as a standard two letter country code 19. The private key size. Select the size of the private key that Zeus Web Server generates. A larger private key is more secure than a smaller one, but can make SSL transactions slower. Importing Existing Files into a Certificate Set i If you have existing pairs of private keys and SSL certificate files, import each pair into a certificate set so that you can use them with Zeus Web Server. You can do this by clicking the Import button and then doing the following: You can upload the files into a certificate set, so that they are fully managed by Zeus Web Server. This is recommended because it enables Zeus Web Server to automatically deploy the files onto other machines in your cluster, when necessary. You can create an unmanaged certificate set by specifying the location of the files, but without Zeus Web Server managing them in any way. If you do this, it is your responsibility to copy the files to the correct location on all the machines in your cluster. Note: Specifying a directory instead of a file when importing files into a Certificate Set may confuse your browser and cause it to lock up. Managing Certificate Sets The certificate set management page displays details of all the currently configured certificate sets. It enables you to create new ones and delete existing ones, as well as helping you with the process of getting certificates signed. 19. The ISO3166 country code list can be found at: Basic Tasks 71

74 The table of configured certificate sets displays the following details for each one: The certificate set name. Click this link to view details about the SSL certificate contained within the certificate set. The certificate s web site. An SSL certificate is registered to a web site, and can only be used to provide security for that web site. How the SSL certificate was signed. When the SSL certificate expires. This is displayed in red if the certificate is to expire within the next month. A link to an action that can be performed on this certificate in order to sign it. If the certificate set is self-signed, this is a link to the certificate signing request page (see Issuing a Certificate Signing Request on page 72 for details). If the certificate is part of the way through a signing request, use this link to continue the signing process. Deleting a Certificate Set To delete a certificate set, click its Delete check box, then click the Delete button. This removes the certificate set from the list, and deletes its private key and SSL certificate files. Issuing a Certificate Signing Request To get an SSL certificate signed by a Certification Authority (CA), send them a Certificate Signing Request (CSR). Zeus Web Server automatically generates this for you when you are creating a signed certificate. The CSR appears in a standard text format that you copy and paste into the Certification Authority s web site. The CSR contains all the details that you entered when creating the SSL certificate. Once the CA has returned a signed certificate to you, copy and paste it into the Signed Certificate section of the Getting Your Certificate Signed by a Certification Authority page. Click the OK button to update the certificate set with the signed certificate. 72 Basic Tasks

75 4.11 Real-Time Monitoring Real-time monitoring enables you to monitor the activity of any of the web server components on the different machines in your cluster. This can be helpful on both development and production systems in the following ways: You use it to determine the effect of using different setups when performing load tests or scalability tests on development systems. You can use it to analyze why a production web site is running sluggishly by looking at the system load and determining where the performance bottleneck on the machine s web server is occurring. The Real-Time Monitoring page displays a graph that shows how often various events occur within Zeus Web Server. You can monitor a wide range of events, such as how many requests the web server is answering, how many times a specific HTTP error page is returned, or how often a particular piece of functionality is used. Basic Tasks 73

76 Access the real-time monitoring page by clicking the Real-Time Monitoring link in the Web Controller menu: i The graph displays a separate colored line for each event that you are currently monitoring. The key below the graph displays a brief description of each monitored event, and the color that represents it. Note: You can also access real-time statistics (in text format) from the command line, by using the zwsstat program located in the $ZEUSHOME/webadmin/bin directory. This program is designed to report real-time performance information in a similar way to vmstat(1). vmstat and zwsstat both report rates per-second. 74 Basic Tasks

77 Selecting Which Events to Monitor To select which events to monitor, click the Change monitored variables button. This displays a list of all the events that can be monitored, grouped under various headings. Individual events that can be monitored have a brief description, and a check box to enable you to select them. Use the list in the following way: To select an event so that it is monitored and displayed on the graph, click its check box. To expand a group heading so that you can see the events within it, click its plus sign. i Once you have selected the events that you want to monitor, click the Apply changes button to return to the graph. Note: Although you can monitor any number of events, selecting a large number can make the graph difficult to read. Configuring the Graph You can configure the real-time graph in the following ways: You can configure how often the graph is updated by entering a sampling period (in seconds). You can configure the total time period that the graph displays historical data for, by entering the period to display (in minutes). If you are running a cluster you can specify which web server on which machine to monitor by selecting the web server name from the drop down list. After you change any of these fields, click the Change monitoring configuration button for the changes to take effect. Basic Tasks 75

78 4.12 Grouped Reports The Real-Time Monitoring pages are also accessible from the Group Reports page, listed in the left-hand configuration menu bar. This groups the variables monitored by web server function, which is useful for quick access to a specific subset of the web server s functionality. For example, one may wish to view the current transfer report, which shows the number of bytes being sent and received, requests served and if there are any timeouts on HTTP requests. By selecting the Transfer Statistics report, this automatically selected the relevant variables to be monitored in realtime, and displays the Real-Time Monitoring page, and the graph of variables is displayed after a short pause Current Connections The Current Connections page gives you a list of all the requests that your web server cluster is managing at that instant. The list includes idle keepalive connections which are not active at that instant. The table lists the following information: Item From To Virtual Server Method URL Host Description The IP address of the remote client. The local IP address that the client connected to. The name of the virtual server managing the request. The HTTP method in the request (GET, POST, HEAD, etc.). The URL that is requested. The Host header in the request. 76 Basic Tasks

79 Item State Description The state of the connection; one of: New: A new connection, where ZWS has not read the HTTP headers; Read: reading request data from the client; Write: writing response data to the client; Idle Bytes in Bytes out Idle: an idle keepalive connection. The idletime - the number of seconds since data was last transferred on this request. The number of bytes read on this request. The number of bytes written on this request. Basic Tasks 77

80 4.14 Using the Traffic History Pages The traffic history pages are useful for viewing recent activity across your web server system. They enable you to view graphs of the traffic over the last week or 24 hour period. 78 Basic Tasks

81 i You can view traffic history in the following ways: Traffic Overview enables you to view the total traffic on specified web servers on different machines, Virtual Servers or Subservers (as described in Using the Traffic Overview Page on page 79). Web Site Comparison enables you to compare the traffic on your busiest web sites by Virtual Server or host header (as described in Using the Web Site Comparison Page on page 80). Cluster Traffic Analysis enables you to compare the traffic on the web servers on different machines in your cluster 20 (as described in Using the Cluster Traffic Analysis Page on page 81). Note: You can only view the traffic history for Virtual Servers that have the statistics gathering functionality enabled (it is by default). For further information, see Traffic History Statistics Gathering on page 176. Using the Traffic Overview Page Use the Traffic Overview page to view the total traffic on specified web servers on different machines, Virtual Servers or host headers. Access the page by clicking the Traffic Overview link in the Web Controller menu. The page displays a graph of total traffic in either hits per minute or bytes per second over the last week or 24 hour period. The total is calculated by adding together the traffic on the specified web servers, Virtual Servers or host headers. 1) Specify what information to plot, in the following way: Select whether you want to view the total traffic on all web servers on all machines in your cluster, or just one of them. If you only want 20. A machine in a cluster may be running more than one web server. If this is the case then the web server is listed using a machine_name:port format. If there is just one web server on a machine then the web server is simply listed by machine name. Basic Tasks 79

82 to see traffic for one web server on a machine, select it in the drop down list. Select whether you want to view the total traffic on all running Virtual Servers, or just one of them. If you only want to see traffic for one Virtual Server, select it in the drop down list. Select whether you want to view the total traffic on all host headers 21, or just one of them. If you only want to see traffic for one host header, click the This host header radio button, then enter the host header name. If you selected an individual Virtual Server in the previous step, the host header you enter must be running on that Virtual Server, otherwise no results will be displayed. 2) Specify how the traffic overview should be displayed, as follows: Specify whether to view hits per minute or bytes per second, by selecting either from the drop down list. Specify whether to view statistics for the previous 24 hours, or previous week, by selecting the value from the drop down list. 3) Click the Plot button for the changes to take effect. Using the Web Site Comparison Page Use the Web Site Comparison page to compare the traffic on your busiest web sites. Access the page by clicking the Web Site Comparison link in the Web Controller menu. The page displays a graph of traffic on your busiest web sites (by Virtual Server or host headers), using a different colored line for each of them. The traffic can be displayed in either hits per minute or bytes per second over the last week or 24 hour period. 21. The Host Header field is used in HTTP/1.1 (and above) to specify the host name and port number (if not using the default port) of the resource being requested. The browser fills the field in from the host name in the original HTTP URL. 80 Basic Tasks

83 The page can also display a five minute snapshot, enabling you to compare the most recent traffic on your busiest host headers. 1) Select which information to plot, in the following way: If you have a cluster of multiple web servers on different machines, select which web server you want to view traffic for. To do this, select the web server in the drop down list. If you want to compare your busiest Virtual Servers, select how many to view on the graph. Note that if a Virtual Server has had no traffic, it will not appear in the graph. If you want to compare your busiest host headers, select how many to view on the graph. You can choose to view just the busiest host headers on a specified Virtual Server, or the busiest host headers across all Virtual Servers. If you want to view the five minute snapshot, click the appropriate radio button. You can choose to view the snapshot for only the busiest host headers on a specified Virtual Server, or for the busiest host headers across all Virtual Servers. 2) Select how the graph of traffic should be displayed, as follows: a) Specify whether to view hits per minute or bytes per second, by selecting either from the drop down list. b) Specify whether to view statistics for the previous 24 hours, or previous week, by selecting the value from the drop down list. 3) Click the Plot button for the changes to take effect. Using the Cluster Traffic Analysis Page Use the cluster traffic analysis page to compare traffic on the web servers on different machines in your cluster 20. Access the page by clicking the Cluster Traffic Analysis link in the Web Controller menu. The page displays a graph of traffic on the web servers on different machines in your cluster, using a different colored line for each. The traffic can be displayed as either hits per minute or bytes per second, over the last week or 24 hour period. Basic Tasks 81

84 Below the graph, all the web servers in the cluster are listed. Clicking the name of a web server in this list takes you to the Traffic Overview page, and displays the total traffic for the web server on this machine. 1) Select how the graph of traffic should be displayed, as follows: Specify whether to view hits per minute or bytes per second, by selecting either from the drop down list. Specify whether to view statistics for the previous 24 hours, or previous week, by selecting the value from the drop down list. 2) Click the Plot button for the changes to take effect Configuring your Preferences Zeus Web Server enables you to configure the following preferences by clicking the Admin/Preferences link in the Web Controller menu: 1) You can specify which page is displayed next after creating a new Virtual Server: Click The Web Controller front page to see the Virtual Server that you have just created in the Virtual Server tree. Click The Virtual Server s configuration pages to continue by configuring the Virtual Server functionality. 2) The Virtual Server tree is folded automatically when the number of Virtual Servers reaches a defined number. Specify this number in the field to ensure that the number of Virtual Servers displayed on the screen at one time (before being automatically folded) does not grow too large. Zeus Web Server then automatically folds the tree when it contains this number of items, and puts this number of items in each fold. 3) By default the running state icons just display the current running state and are not clickable. You can configure them to be clickable so that you can use them to start and stop the Virtual Servers by setting the appropriate radio button. Note that you should only do this if you are an expert user because it makes it easier to stop or start the wrong Virtual Server by mistake. 82 Basic Tasks

85 4) Click the Apply changes button to update your preferences Configuring Administration Security Zeus Web Server enables you to monitor and manage your web server machines remotely, using a web browser. It is therefore recommended that you ensure that it can only be accessed by specified users in a secure way. Configure these security settings in the following way: 1) Click the Admin Security link to access the security settings page. 2) Use the Access Restrictions section to restrict access to the user interface pages to specified host names or domains. You can enter full regular expressions in this field by prefixing them with a ~. For details on using regular expressions, see Using Regular Expressions on page 389 3) Use the SSL Secure Connection section to configure and enable SSL security on connections to the Administration Server. This enables you to access the user interface pages securely. Do this as follows: a) To use SSL security, you must have a suitable SSL certificate set 22. In this case, a self-signed SSL certificate set is appropriate, as only you are accessing the pages. If you have already created such a certificate set, select it in the drop down box. If not, do one of the following: Generate and use a new self-signed SSL certificate set automatically by clicking the button. Create and use a new signed SSL certificate set by following the SSL Certificates management page link, creating the certificate set there, and then returning to this page to select it in the drop down box. b) Enable SSL by setting the Use SSL radio button. 22. For more information about SSL security, refer to Web Server Security on page 34. Basic Tasks 83

86 4) Use the Administration Password section to change the password that you use to log in to and access user interface pages. Choose a new password and enter it into both fields. Once you have applied this change you will need to use this new password next time you start the Administration Server. 5) Click the Apply changes button to make these changes Sending a Technical Support Query Access the technical support query page by clicking the Technical Support link in the Web Controller menu. To send a query to Zeus Technical Support, do the following: 1) Supply as many details as you can about the problem that you are encountering. Provide a clear description of the symptoms of the problem and as much information as possible about how to recreate it. These details will help the support team resolve your query as quickly as possible. Note that the form automatically detects and optionally includes system configuration information. 2) Click the Review Support Query button to generate the information that will be sent to the Zeus technical support team. Zeus Web Server checks that the fields have been completed correctly, and collects the specified information. 3) Specify how to send the information to Zeus: To send the information directly to the Zeus support web site, click the Submit query direct to Zeus button. To automatically the information to Zeus, click the Submit query by button. To do this, you must have sendmail (or an equivalent program) installed and correctly configured on the Administration Server machine. To download the information to your computer so that you can attach it to an message, click the Download query to your 84 Basic Tasks

87 computer button. Send the file to quoting your customer account number in the subject line of the . The full text of the query is displayed at the bottom of the page to enable you to review it before you send it. Basic Tasks 85

88 86 Basic Tasks Zeus Web Server 4.3 User Guide

89 CHAPTER 5 Configuring Virtual Server Functionality 5.1 Introduction Once you have created a Virtual Server, the next step is to configure the functionality that will be available to support the Virtual Server s web site. There are two parts to setting up the functionality for each Virtual Server: You can enable and disable functionality. This means that you can disable any unwanted functionality in order to maximize the performance of your Virtual Server s web site, and to improve security (by preventing users from having access to potentially powerful functionality) 23. You can configure the functionality. This configuration information is preserved when the functionality is disabled so that you only need to configure it once. This chapter provides an overview of the functionality that is available, and describes how to enable and disable it. The following chapters provide more detail about the functionality that is available and how to configure it. The Virtual Server configuration summary page provides a list of what functionality is enabled for each Virtual Server (but does not provide any configuration detail). 23. For example, by disabling CGI scripts, or directory listings. Configuring Virtual Server Functionality 87

90 5.2 Functionality Overview Zeus Web Server always provides the most basic core web server functionality for every Virtual Server that enables it to respond to requests for static content by retrieving and sending back the file 24. You can also configure the following functionality for each Virtual Server: You can view and configure the Virtual Server s general settings as described in General Configuration Information on page 95. You can configure how the Virtual Server handles files, as described in Configuring File Handling on page 105. You can configure how the Virtual Server handles requests for files and directories, as described in Configuring URL Handling on page 125. You can configure how the Virtual Server logs and displays its activity, as described in Configuring Logging and Monitoring on page 165. You can configure who can view different areas of your web site, and how much bandwidth different web sites can use, as described in Configuring Access on page 185. You can configure support for external applications using a number of different APIs, as described in Configuring API Support on page 209. You can create and configure Subservers, as described in Configuring Subservers on page 253. You can integrate the Virtual Server with a number of add-ons, as described in Configuring Add-Ons on page 267. The chapters that follow provide more information about this functionality and how to configure it. 24.You might, however, want to disable static file serving for a shopping cart web site that passes all requests to an external application. This is possible by modifying the configuration files directly. For more information about configuration files, refer to Scripting Overview on page Configuring Virtual Server Functionality

91 5.3 Using the Configuration Pages The configuration pages display the configuration information for the selected Virtual Servers. This section describes the layout of these pages and how to use these pages to configure one or more Virtual Servers. Overview of the Layout of the Configuration Pages This section describes the layout of the configuration pages. Summary Bar Status Indicators Button Bar Configuration Page Menu Main Page Area The following section describes each of the basic tasks that you can use this page to carry out. Summary Bar This summarizes the items that you selected in the Virtual Server Status page, and are currently configuring. It indicates whether you have selected one Virtual Server, multiple Virtual Servers or a group, and so on. Configuring Virtual Server Functionality 89

92 It also provides status information about the configuration changes that you have made in the following way: Status Indicators Indicator Name Icon OK Indicator Attention indicator Uncommitted Configuration Changes indicator... indicates that the... configuration changes that you have just submitted have been made successfully to the edited configuration. configuration changes that you have just submitted generated either errors or warnings. See Resolving Errors and Warnings on page 93. This indicator shows that the configuration for the Virtual Server(s) that you are currently editing has changes that have not yet been committed to the running Virtual Server. This is exactly the same as the Configuration changes icon on the Virtual Server Status page. See Committing Configuration Changes on page 61. Button bar Button Name Use it to... Documentation... view the online documentation. Home... return to the Virtual Server Status page. Configuration page menu The configuration page menu provides links to the individual configuration pages, and a summary page. Main screen area The main screen area displays the configuration pages. Specify values in each and then click the page's Apply changes button. Each time you 90 Configuring Virtual Server Functionality

93 update a page the status indicators at the top of the page update to display the status of that change. Configuring a Single Virtual Server If you select one Virtual Server from the Virtual Server status page you can then configure its functionality in much the same way that you could for previous versions of Zeus Web Server. Configuring Multiple Virtual Servers Zeus Web Server enables you to select and configure multiple Virtual Servers easily so that you can ensure that specific configuration settings are consistent across them. If you select multiple Virtual Servers (either by selecting multiple individual Virtual Servers or by selecting a group) then you can configure almost all the Configuring Virtual Server Functionality 91

94 same items that you could for an individual Virtual Server 25. The values across the selected Virtual Servers are shown in the following way: If all the selected Virtual Servers are configured with the same value then just this value is shown: If the selected Virtual Servers have different values for particular configuration parameters then these are displayed. For example: In this case you are given the following options: You can make all the values consistent in one of the following ways: You can specify one of the existing values from a drop down box. This is then applied to all selected Virtual Servers. You can specify a new value, in a field. This is then applied to all selected Virtual Servers. You can leave the values set as they are (inconsistently across the selected Virtual Servers) This enables you to make a set of values consistent across a number of Virtual Server very easily. It is designed to highlight the differences between them. If you select multiple Virtual Servers that are configured very differently then the configuration pages will contain a lot of detail about the differences in the configuration. In this case it makes more sense to view the configuration of each Virtual Server individually. 25.You cannot however configure access rules or SSL security across multiple Virtual Servers at once. 92 Configuring Virtual Server Functionality

95 Resolving Errors and Warnings When the Attention indicator is displayed, this indicates that the configuration changes that you have just submitted generated either errors or warnings. The nature of the problem that caused each warning or error is displayed in red text beside the field that should be changed. Errors indicate that this configuration change cannot be made. The value must be corrected and submitted again. Warnings indicate that there was something unusual or unexpected in the configuration change, indicating that it might have been specified incorrectly. If just warnings (and no errors) are generated, you can choose to override them by clicking the Override check box that appears beside the Apply changes button, and clicking the button again. The OK and Attention indicators then both light up to indicate that the changes have been made successfully to the edited configuration even though warnings were generated. Indicator Summary The following table summarizes the meanings of different combinations of indicators: Indicators:... show that... the changes have been successfully applied to the edited configuration. the changes have generated errors or warnings and so they have not been applied to the edited configuration. warnings have been overridden: the changes have been successfully applied to the edited configuration even though warnings were generated. Configuring Virtual Server Functionality 93

96 94 Configuring Virtual Server Functionality

97 CHAPTER 6 General Configuration Information 6.1 Introduction Virtual Servers have the following general configuration information associated with them: The Configuration Summary page provides a list of the Virtual Server s basic settings and lists what functionality is enabled. See Viewing the Configuration Summary on page 96. The Request Processing Summary page gives an alternative list of what functionality is enabled for a Virtual Server. See Viewing the Request Processing Summary on page 96. The Fundamental Configuration Settings page provides the basic Virtual Server settings, as described in Fundamental Configuration Settings on page 98. The Advanced Configuration Settings page provides access to more advanced settings, as described in Advanced Configuration Settings on page 98. The SSL Security pages enable you to configure the SSL settings for your Virtual Server, as described in Configuring SSL Security for a Virtual Server on page 100. General Configuration Information 95

98 6.2 Viewing the Configuration Summary To view the configuration summary, click the Config Summary link in the configuration page menu. Zeus Web Server displays the following: The basic configuration settings. This enables you to see a summary of the basic settings of the selected Virtual Server(s) (such as names and addresses) easily. The enabled functionality. This enables you to see which functionality is enabled or disabled for the selected Virtual Servers. This can be helpful if you are trying to see whether a set of Virtual Servers has the same functionality enabled. To modify any of these, click the link beside each to go to the page where it is set. Renaming a Virtual Server The Virtual Server name is used as the identifier for all the information associated with the Virtual Server. This means that you cannot change it while the Virtual Server is running. To rename a Virtual Server, stop it and click the Config Summary link in the configuration page menu. Edit the Virtual Server Name field. 6.3 Viewing the Request Processing Summary To view the request processing summary, click the Processing Summary link in the configuration page menu. Zeus Web Server displays the following: A list of the processing stages that Zeus Web Server goes through to process an HTTP request. The functionality that is enabled at each processing stage for the selected Virtual Server(s). This summary illustrates the dependencies between each item of functionality, and the number of features that are enabled for the selected Virtual Server(s). 96 General Configuration Information

99 Request Processing reference When Zeus Web Server processes an HTTP request, it goes through a number of stages: 1) Processing HTTP Headers: This stage is run to read the headers from the connection. 2) Mapping Request to Filename: This stage is run to inspect the requested URL and apply the mapping rules to determine the resource that is requested. 3) Processing Filename: This stage is run to fix-up the filename according to supplementary resource location rules such as content negotiation or redirects as a result of a directory request. 4) Calculating MIME Type: This stage is run once the requested resource has been determined; it calculates the MIME type of the resource. 5) Checking Permissions: This stage is run if any authentication methods have been configured; it verifies that the client is authorized to access the requested resource. 6) Generating HTTP Response: This stage generates the HTTP response based on the resource requested and its MIME type. Zeus Web Server includes a default generation state which handles resources which correspond to files on disk. 7) Completing HTTP Request: This stage is run once the HTTP response has been sent successfully to the remote client; it is commonly used to log request data. Several special stages exist as well: 1) Writing Data to Client: Functionality that is configured to run at this stage can modify the data that is written to the client. Content compression is an example of functionality that works in this way. 2) Handling Errors: If a connection encounters an error during processing, this stage is run to return an error message to the client and close the connection. General Configuration Information 97

100 6.4 Fundamental Configuration Settings To view the Virtual Server s basic configuration information, click the Fundamentals link in the configuration page menu. This displays the information that you configured when you created the Virtual Server and enables you to modify these settings. For more information about each of these fields refer to Creating a New Virtual Server on page Advanced Configuration Settings To view the Virtual Server s advanced configuration information, click the Advanced Settings link in the configuration page menu. This displays the 98 General Configuration Information

101 Virtual Server s advanced configuration information which you can view and modify in the following way: Set this field... DNS Lookup... to... specify whether the Virtual Server should perform a DNS lookup that relates IP addresses (such as ) to host names (such as or not, in the request logs. Setting this makes it easier for you to see which machines people are accessing your pages from, because their host names, rather than IP addresses are logged. For more information about recording request information, refer to Configuring Request logging on page 165. You must also set this if you want to restrict access to your web site from specified named domains. However, you should be aware that using DNS lookup increases the load on the web server and so is not recommended for heavily loaded web sites. General Configuration Information 99

102 Set this field... Bind address i Bind port... to... a comma separated list of bind addresses that the Zeus Web Server will bind to for this Virtual Server, and that override the host name and port combination. This can be thought of as configuring the Virtual Server to listen on the specified bind address(es), as the host name. Set this field if you want the Virtual Server physically to bind to different IP addresses from the one specified in the host name and port section. The Virtual Server then still listens as if it were the specified host name. You can specify %machine% in this field in order to specify the machine name. The macro is simply expanded to the local web server machine name. This can be useful when setting up Virtual Servers to run on clusters, as described in Publishing a Web Site on a Cluster on page 288. a port that the Zeus Web Server will bind to for this Virtual Server, and that overrides the port in the host name and port combination. This can be thought of as configuring the Virtual Server to listen on the specified bind port as the port specified in the host name. Set this field if you want the Virtual Server physically to bind to a different port from the one specified in the host name and port section. The Virtual Server then still listens as if it were the specified port. i. It is recommended that you only use these fields if you are familiar with bind(). 6.6 Configuring SSL Security for a Virtual Server To configure a Virtual Server s SSL settings, click the SSL Security link in the configuration page menu. The SSL security page enables you to configure whether the Virtual Server uses SSL security, and which SSL certificate set 26 it uses to do this. If you have not already configured a certificate set, this page enables you to create a simple self-signed certificate set, suitable for testing 26.Certificate sets are a convenient way of managing your SSL certificate files and private keys. For more information, see Setting up Virtual Server SSL Security on page General Configuration Information

103 purposes only. To create and manage signed certificates, use the Certificate Set Management page, as described in Setting up Virtual Server SSL Security on page 68. Enabling SSL Support for a Virtual Server To enable SSL support for a Virtual Server, do the following: 1) Access the SSL security page by clicking the SSL Security link in the configuration page menu. 2) Enable SSL security by clicking the appropriate radio button. When a web server uses SSL security, it normally uses port number 443 rather than port 80, and you are recommended to choose this option. Zeus Web Server automatically re-configures the port number (if required) and changes the Virtual Server URL to start with 3) Select the SSL certificate set that you want to use. If there are no configured certificate sets then you must create one. For information on how to do this, see Creating an SSL Server Certificate Set on page 102. Note that if you have upgraded to Zeus Web Server version 4, and you were previously using SSL security, then Zeus Web Server displays the file names of your existing certificate file and private key. Although you can continue using these files without using a certificate set, you are recommended to import them into a certificate set so that Zeus Web Server manages them for you. For more information, see Importing Existing Files into a Certificate Set on page 71. 4) In the Requesting Client Certificates section, specify whether the Virtual Server should require certificates from browsers (clients) in order to authenticate individuals. Do this by clicking the appropriate radio button. 5) Click the Apply changes button. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. i Note: If you use a self-signed SSL certificate to secure your web site, visitors may see a warning when they first view the web site contents. This is because your General Configuration Information 101

104 certificate has not been signed by a recognized Certificate Authority (CA), and therefore cannot be trusted. Visitors will need to accept the certificate to continue viewing the web site.! In order to obtain a signed certificate you must generate a Certificate Signing Request (CSR) and send it to a recognized Certificate Authority 27. You can do this either by following the instructions for purchasing a certificate from Veri- Sign (which is integrated with the Zeus Admin Server pages), or by creating the request and sending it out yourself. Refer to Issuing a Certificate Signing Request on page 72 for information on how to do this. Warning: Once SSL security has been set up, existing bookmarks for web pages on your Virtual Server will no longer work because the URL has changed to start with Delete the existing bookmarks and create new ones. Creating an SSL Server Certificate Set You can automatically generate an SSL server certificate set composed of a self-signed SSL certificate and a private key, simply by clicking the Generate a Test Certificate button. The certificate set is named after the Virtual Server that you are currently configuring, and the Virtual Server is configured to use this certificate set. If you want to create a signed server certificate set, use the certificate set management page, as described in Setting up Virtual Server SSL Security on page 68. Using SSL Client Certificates A Client Certificate is an SSL certificate that is held by the browser (rather than by the Virtual Server). It is a secure piece of information that identifies the client (the browser) to the Virtual Server. You can choose what authentication policy to use when configuring the use of client certificates. For example, your authentication policy may specify that the Virtual Server 27.Note that you will need to pay for a certificate from a widely recognized Certificate Authority (such as VeriSign, see and wait for it to be delivered. In the meantime you can use a self-signed certificate for testing purposes. 102 General Configuration Information

105 requires a valid client certificate before it will respond to a request. Alternatively, your authentication policy may use a hybrid model, where the client may supply a certificate if it wishes. Why are SSL Client Certificates useful? SSL client certificates are signed by a trusted authority, and when used properly, this can make them more secure than other authentication methods (for example, access based on a user s password or IP address). The SSL client certificate is installed into the user s browser, and is presented to the Virtual Server when the browser initiates an SSL connection. The Virtual Server can be configured only to allow access when a valid certificate is presented. In addition, the client certificate will also store additional information that can be made available to the web site, for example, the name and details of the user. The certificate information can be supplied to an application by means of CGI environment variables, and also via ISAPI or NSAPI function calls. When a Virtual Server receives a client certificate, the following checks are made: It verifies the certificate is signed by a Certificate Authority (CA) it has been configured to trust. It verifies the certificate against all its configured certificate revocation lists. It verifies the certificate s issued and expiry dates are valid for the current time. If all the above check pass, then the Virtual Server accepts the certificate. Configuring the Locations of Public Certificates and Revocation Lists If you have configured the Virtual Server to check client certificates then you need to obtain and store the root certificates of the CAs you trust. Certificate Authorities may also issue certificate revocation lists (CRLs) and if you obtain one, it must be saved to disk using the.crl file extension. Store these files in a directory on your system which is not publicly accessible. You then need to configure the Virtual Server with the location of this directory. General Configuration Information 103

106 To configure SSL client certificate authentication for a Virtual Server, do the following: 1) Access the Client Certificates page by clicking the link listed under SSL Security in the configuration page menu. 2) Under Requesting Client Certificates, select the appropriate authentication policy you wish to use, i.e. whether client certificates are mandatory for access for not. 3) Under Validating Client Certificates, add the path to the directory containing the certification validation information (public certificates and optional CRLs) in the New Location text box. If this path is a directory, then files in this directory ending in.crl are assumed to be certificate revocation lists, and other files not ending in.crl are treated as public certificates. 4) If appropriate, change the settings of SSL Client Certificate Detailed Logging so that failed attempts are logged to the error log. 5) Commit your changes for this Virtual Server. Reloading a Virtual Server with updated certificates and CRLs When new public certificates or CRLs are available, you should update these on your filesystem. The Virtual Server will reload certificate validation information (public certificates and CRLs) when: committing a new configuration for this Virtual Server or selecting the Reload Locations button Selecting the Reload Locations button will update the certificate validation information without restarting the Virtual Server, so that any current network connections to this Virtual Server will not be closed. Any errors in processing these files will be shown with the details of why they are invalid. The certification validation information can also be reloaded from the command line using the webctl program (See The webctl Script on page 372) 104 General Configuration Information

107 CHAPTER 7 Configuring File Handling 7.1 Introduction Virtual Servers use files in a number of different ways. You can configure how each Virtual Server handles files in the following ways: To configure MIME types, refer to Configuring MIME Types on page 105. To configure content negotiation, refer to Configuring Content Negotiation on page 108. To configure content compression, refer to Configuring Content Compression on page 120 To enable users to upload files to the web site, refer to Configuring File Uploading on page Configuring MIME Types The MIME type is the information returned with each requested file, that the browser uses to determine how to handle and display the file. To configure which MIME type the Virtual Server returns for different file types, configure the MIME types functionality. For example, files with the extension.html are usually associated with the MIME type text/html, and.gif files are associated with the type image/gif. Configuring File Handling 105

108 The MIME types configuration page lists all the current MIME type associations, and which one is used as the default. Configuring the Default MIME Type The default MIME type is the one returned by Zeus Web Server for any unknown file type. Normally this is set to text/plain, which tells the browser to treat unknown file types as if they were text. You can change this to any MIME type by entering a new value in the Configuring the Default MIME Type section, and clicking the Apply changes button. i For example, if you want browsers to treat unknown files as HTML, then change the default MIME type to text/html. Note: Browsers are more likely to display unknown file types in a meaningful way if the default MIME type is left as text/plain. Adding a MIME Type If you have files on your system that have a file extension not listed in the table of MIME types, add this file extension to the list. For example, to enable Shockwave Flash files on your web site, add the following MIME type to the table: Extension swf MIME type application/x-shockwave-flash Add new MIME types in the following way: 1) Access the MIME types page by clicking the MIME Types link in the configuration page menu. 1) In the Adding a MIME Type section, enter the File Extension without the preceding dot. File extensions are case sensitive. 106 Configuring File Handling

109 2) Enter the MIME type. To find out the correct MIME type for a particular file type, consult the documentation for the application that produced the file. 3) Click the Apply changes button. The new MIME type is added to the list of Assigned MIME types. Deleting a MIME Type To delete a MIME type from the list of assigned MIME types, do the following: 1) Click the Delete check box next to the MIME type that you want to delete. 2) Click the Apply changes button. Modifying a MIME Type To modify the MIME type corresponding to a file extension, do the following: 1) Find the file extension in the list of assigned MIME types. The file extensions in this list appear in alphabetical order. 2) Edit the File extension or MIME type directly in the list. 3) Click the Apply changes button at the bottom of the page. Automatic MIME Type Detection Zeus Web Server can automatically detect the mime type of a response if the MIME types table does not contain an entry. This is a fallback feature for static content of an unknown type. It overrides the default mime type configured on page 106. This feature is disabled by default as it imposes a performance penalty and it may not calculate the correct MIME type if the file s signature is not in ZWS s database. To enable this feature: 1) Set the radio button in the Automatic MIME Type Detection section to Enabled. 2) Click the Apply changes button at the bottom of the page. Configuring File Handling 107

110 7.3 Configuring Content Negotiation Content negotiation is useful on web sites that have content available in different versions, such as web pages in more than one language. It enables multiple versions of a web site to coexist in one location and be delivered to users appropriately and transparently. When a user requests a page from such a web site, content negotiation ensures that they automatically receive the version of the web page that they can understand. Content negotiation makes multi-language web sites easier for the user to navigate. The user only needs to specify their preferred language once (within their browser), and content negotiation makes sure that they receive pages in their preferred language, whenever they exist. Content negotiation is normally used on multi-language web sites, but can also be used whenever web content is available in more than one format, such as different character set encodings. It returns the most suitable versions of web pages to users, based on their preferences, and their browser s ability to display content. How Users Configure Browsers for Content Negotiation Language content negotiation attempts to return files to users in their preferred language. It can only do this if the user has configured their browser appropriately. They do this by specifying a list of languages that they can understand, ranked according to preference, in their browser s configuration pages 28. The browser sends this information to the web server with every request it makes, enabling the web server to return the requested page in the appropriate language. Some browsers are automatically configured with a language preference when they are installed, but others are not. If the browser is not configured with a preferred language, content negotiation returns the file in the web site s default language as defined in the content negotiation configuration 28.To configure the preferred language in Internet Explorer 5, use Tools / Internet Options / Languages. To configure the preferred language in Netscape 4.7, use Edit / Preferences / Languages. 108 Configuring File Handling

111 page. For information on how to configure this, see Configuring Language Negotiation on page 113. How Content Negotiation Works Content negotiation automatically selects the most suitable version of a requested file from all the alternative versions that are available. When preparing a web site to use content negotiation, store each version of a web page in a separate file, and identify it using an extra file extension to specify its format. Zeus Web Server uses these additional file extensions to determine which file best matches the user s specified preferences. Naming Files In order for content negotiation to work, files must be named appropriately. Each file name is made up of the root name that identifies the requested resource (this is the same for all versions of the file) plus a number of file extensions that define its language, MIME type, and so on. You define these file extensions, and what they represent, in the Virtual Server. For example, if you have a web page available in both English and French, these could be named mypage.english.html and mypage.french.html. i Note: When using content negotiation, file names can have more than one file extension, and these can be used in any order. For example, index.english.html and index.html.english are considered equivalent. However, you are recommended to use the MIME type file extension last, to preserve the mapping from file name to MIME type, which is especially important if you are using an HTML editor to maintain the web site. How Users Request Files Although multiple versions of each file can exist on the web site, with different file extensions, this is transparent to the user. Users simply see their preferred version of the file. Configuring File Handling 109

112 Users request files by asking for them without specifying the additional file extensions in their name. For example, if the user requests the URL the virtual Server chooses the most suitable version of this file (perhaps index.spanish.html), and returns it to them. This process is transparent to the user it appears to them that they simply receive the file they request. Linking between Pages When using content negotiation, web pages are requested by using their file names without any of the extra file extensions. Links between pages on the web site also work in this way. For example, to create a link to the appropriate home page (either /index.english.html or /index.french.html), simply create a link to /index.html. When a user follows this link, the appropriate version of the file is returned automatically. How Files are Returned The Virtual Server uses content negotiation to choose the most appropriate version of the requested file. It does this in the following way: 1) It searches the appropriate directory for a file name exactly matching the one requested. If it finds one, this file is returned and no content negotiation takes place. 2) If no exact match is found, it looks for all the files whose root name matches the requested file name, ignoring the file extensions. It then compares the extra file extensions of all the matching files to the user s preferences, and does the following: If the user has ranked their language preferences, the version in the highest ranked language is returned 29. If the user has not configured any language preference (or has given equal ranking to their preferred languages), and one of the available files is in the web site s default language, then this file is returned. For example, if the user has not configured a language preference in 29.Most browsers force the user to rank their preferred languages in some way. 110 Configuring File Handling

113 their browser, and the requested file exists in French and German, then the version in French is returned if French is the default language for the web site. If the user has not configured any language preference, and none of the available files is in the web site s preferred language, then one of the files is returned at random. 3) If no files match, the Virtual Server generates a web page containing links to the alternative files that are available. It returns this page to the user with the HTTP status code 406 ( Not Acceptable ). This web page enables the user to decide whether to view any of the available files, and which one to view. For example, the user may have specified that they only want web pages in English, but the requested file is available only in French and German. The Virtual Server returns a web page containing links to these two versions of the file. Types of Content Negotiation Content negotiation is typically used when web pages are available in more than one language, to ensure that the most appropriate version is returned to the user. It can do this because the user specifies their language preferences. However, it can also be used when web site content is available in more than one format, such as a web page in different character set encodings. The user s browser may only be able to display files in certain formats, so content negotiation ensures that the web server returns the most suitable version of the file to the browser. It can do this because the browser specifies which formats it can display each time it makes a request. Zeus Web Server can perform the following types of content negotiation: Language Negotiation Use this when you have individual web pages available in more than one language. The user configures their preferred language in their browser. Configuring File Handling 111

114 The web server returns a version of the requested web page in the preferred language, if it is available. Character Set Negotiation. Use this when you have individual web pages available in more than one character set encoding. Specify a unique file extension for each character set encoding, and use these in the file names. Each time the user requests a file, the browser sends information with the request, telling the Virtual Server which character sets it is able to display. The Virtual Server returns the appropriate version of the file to the browser, if it is available. For example, if you have a web page available in Japanese using either the ISO 2022 character set, or the Shift-JIS character set, you could make these available on your web site as index.japanese.iso html and index.japanese.sjis.html. Encoding negotiation Use this when you have individual web pages that are compressed in different ways. Specify a unique file extension for each compression method, and use these in the file names. Each time the user requests a file, the browser sends information with the request, telling the Virtual Server which compression methods it can handle. The Virtual Server returns the appropriate version of the file to the browser, if it is available. MIME type negotiation Use this when you have individual files on your web site that are available in different media types. For example, you may have a single image that is available as a.gif or a.png file. Each media type has a file extension associated with it, used at the end of the file name to tell the Virtual Server the MIME type of the file. For example, image1.gif and image1.png. Each time the user requests a file (in this example, when they request image1), the browser sends information with the request, telling the Virtual Server which MIME types it prefers. The Virtual Server returns a suitable version of the file to the browser. 112 Configuring File Handling

115 Configuring Content Negotiation on the Virtual Server Content negotiation returns the preferred version of a file to the user by matching its file extensions to the user s preferences and their browser s capabilities. In the Virtual Server, configure how the file extensions relate to the file versions for each file extension you use on your web site. For example, if you have versions of a file available in different languages, assign a file extension to each language, and then specify how each of the file extensions maps to a standard set of language codes 30. For example, you could map the language file extension.british to the language code en-gb. Configuring Language Negotiation To configure the Virtual Server to perform content negotiation for files available in more than one language, do the following: 1) Go to the content negotiation configuration page and enable content negotiation. 2) In the Language Negotiation section of this page, enable language negotiation. 3) Enter the Default language code 31 for your web site. The Virtual Server uses this when deciding which version of a file to return if there are multiple files that equally satisfy a user s request. For further details, refer to How Files are Returned on page ) Use the Adding a Language section to add each of the languages used on your web site, as follows: a) Enter the File extension (without the preceding. ) that you use for this language. b) Enter the Language code 31 for this language. c) Click the Apply changes button. Each language you add is displayed in the table of Assigned Language Codes. 30. The standard language codes are defined in The standard language codes are defined in Configuring File Handling 113

116 Modifying an Assigned Language Code To modify an assigned language code, edit its File extension or Language code directly in the Assigned Language Codes table, then click the Apply changes button. Deleting an Assigned Language Code To delete an assigned language code, click its Delete check box, then click the Apply changes button. Configuring Character Set Negotiation To configure the Virtual Server to perform content negotiation for files available in more than one character set, do the following: 1) Go to the content negotiation configuration page and enable content negotiation. 2) In the Character Set Negotiation section of this page, enable character set negotiation. 3) Enter the Default character set code 32 for your web site. The Virtual Server uses this when deciding which version of a file to return if there are multiple files that equally satisfy a user s request. For further details, refer to How Files are Returned on page ) Use the Adding a Character Set section to add each of the character sets that your web site uses, as follows: a) Enter the File extension (without the preceding. ) that you use for this character set. b) Enter the Character Set code 32 for this character set. c) Click the Apply changes button. Each character set that you add is displayed in the Assigned Character Set Codes section. 32.The standard character set codes are defined in Configuring File Handling

117 Modifying an Assigned Character Set Code To modify an assigned character set code, edit its File extension or Character Set code directly in the Assigned Character Set Codes table, then click the Apply changes button. Deleting an Assigned Character Set Code To delete an assigned character set code, click its Delete check box, then click the Apply changes button. Configuring Encoding Negotiation To configure the Virtual Server to perform content negotiation for files available in more than one encoding, do the following: 1) Go to the content negotiation configuration page and enable content negotiation. 2) In the Encoding Negotiation section of this page, enable encoding negotiation. 3) Enter the Default encoding 33 for your web site. The Virtual Server uses this when deciding which version of a file to return if there are multiple files that equally satisfy a user s request. For further details, refer to How Files are Returned on page ) Use the Adding an Encoding section to add each of the encodings that your web site uses, as follows: a) Enter the File extension (without the preceding. ) that you use for this encoding. b) Enter the Encoding 33. c) Click the Apply changes button. Each encoding that you add is displayed in the Assigned Encodings section. 33. The standard encodings are defined in Configuring File Handling 115

118 Modifying an Assigned Encoding To modify an assigned encoding, edit its File extension or Encoding directly in the Assigned Encodings table, then click the Apply changes button. Deleting an Assigned Encoding To delete an assigned encoding, click its Delete check box, then click the Apply changes button. Configuring MIME Type Negotiation To configure the Virtual Server to perform content negotiation for files available in more than one media type, do the following: 1) Go to the content negotiation configuration page and enable content negotiation. 2) In the MIME Type Negotiation section of this page, enable MIME type negotiation. 3) The assumed MIME type for your web site is displayed on the content negotiation page, but cannot be edited from here. The Virtual Server assumes a file has this MIME type if it does not have a MIME type file extension. To configure the assumed MIME type, go to the MIME types page and configure the default MIME type field. 4) Enter the preferred MIME type for your web site. The Virtual Server uses this when deciding which version of a file to return if there are multiple files that equally satisfy a user s request. For further details, refer to How Files are Returned on page ) Click the Apply changes button. MIME types are already configured on your Virtual Server. To see the assigned MIME types, click the MIME Types link in the configuration page menu. 116 Configuring File Handling

119 Designing a Web Site to use Content Negotiation When designing a web site to use content negotiation, bear in mind the following: You are recommended to use a web site editing and design tool that is aware of content negotiation. Tools that are not aware of content negotiation will view the links between files on your web site as broken links, because they do not link to existing files. Some users may have configured the language preference in their browser incorrectly, or may never have configured it at all. For this reason you are recommended to make explicit links to the other language pages at the top level of your web site, and to inform users that your web site uses content negotiation. Some third-party tools such as automatic web site indexers may not be compatible with content negotiation, and so may not be able to find and index other language versions of your web site. Making explicit links to other language versions on your web site can help these tools. You do not need to implement all pages in a web site in multiple languages. Simply ensure that pages that are only available in one language do not use any of the language file extensions. This ensures that they are returned to all users whatever they have specified their language preferences to be. If you are using language negotiation with any other type of content negotiation, you can create default files that are returned to users if their preferred language versions are not available. Do this by creating a version of the file with no language file extension. For example, if you are using language negotiation and encoding negotiation together, you could create two files, one called index.gz.html and the other called index.japanese.gz.html. Users who have specified Japanese in their browser s language preferences will receive the Japanese version of the file, but all other users will receive the version without a language file extension. Configuring File Handling 117

120 Adapting an Existing Web Site to use Content Negotiation If you have an existing web site in one language only, and want to translate some pages into an additional language, do the following: 1) Configure the file extensions and language codes for each of the languages you are using. 2) Translate the pages into the second language, and name each new file with the appropriate language file extension. 3) Rename all the original files to use the language file extension of the original language. 4) Set the web site s default language code to the original language of the web site. This determines which version of a file is returned if the user expresses no preference. 5) Enable content negotiation. If you have an existing web site in more than one language, and want to start using content negotiation, do the following: 1) Configure the file extensions and language codes for each of the languages you are using. 2) Create multiple versions of the home page, one in each language, and name them using the corresponding file extension. 3) From each language-specific home page, link explicitly to the existing web sites in the corresponding language. 4) Enable content negotiation. It is more efficient to implement your web site in this way, using content negotiation only on the home page, and direct links to files everywhere else. This is because content negotiation requires extra processing, placing an additional load on the Virtual Server. 118 Configuring File Handling

121 Language Content Negotiation of HTTP Error Pages You can configure Zeus Web Server to return HTTP error pages to users in their preferred language. The pages are returned in the following way: 1) When a Virtual Server needs to return an error page to the user, it searches in the customized HTTP error page directory 34 for an error page in the user s preferred language. If it finds an appropriate file (such as 404.spanish.html), it returns it to the user. 2) If an error page cannot be found in the preferred language, then the original error file (such as 404.html) is returned. To configure a Virtual Server to perform content negotiation of error pages, do the following: 1) Enable content negotiation, and configure language negotiation, as described in Configuring Language Negotiation on page ) If you have disabled customized error pages, re-enable them, as described in Customizing HTTP Error Pages on page ) In the customized HTTP error page directory, create new versions of the error pages in each language, and name them appropriately, for example, 404.english.html or 404.french.html. Be sure to leave the original error files, such as 404.html, where they are. Ensure that you commit the configuration for the changes to take effect. Zeus Web Server will then return error pages to the user in their preferred language, if they are available. Otherwise the user will receive the original error page. 34. For information about the HTTP error page directory, see Specifying the HTTP Error Page Location on page 174. Configuring File Handling 119

122 7.4 Configuring Content Compression Introducing Content Compression Some browsers are able to receive compressed content from web servers. The browser then uncompresses the content before displaying it in the usual way. Browsers seamlessly negotiate whether they can handle compressed files with the web server. i Content Compression enables you to configure Zeus Web Server to transparently return compressed content to browsers that support this 35. This means that less data needs to be sent to a browser in the response, which can reduce the response time over a slow connection. Note: This functionality configures compression on a per-virtual Server basis. To configure it on a per-directory basis you can use the htaccess directives, ContentCompressionEnabled or ContentCompressionDisabled, as described in Content Compression Directives on page 364. Enabling Content Compression When configuring compression you need to understand its effects so that you can configure it appropriately for a particular web site. An uncompressed file is returned immediately to the user. A compressed file must first be compressed by the web server (if it has not been compressed before), returned to the user and then uncompressed by the browser. This means that when files are compressed, the web server and browser will spend longer processing the request, but the transit time of large files over slow connections is reduced. This means that content compression is most effective if you are running a web site on a very fast machine with users accessing it over slow links (such as mobile phone connections or modems). In this case the speed of the web site response is mostly determined by the time taken to transfer the file to the user, and the transfer time may be decreased using compression. 35.This functionality is similar to that provided by Apache's mod_gzip 120 Configuring File Handling

123 However if you are running a web site on a slow machine, which has users typically connecting over very fast links, then compression will offer little benefit because the time taken to compress the content will outweigh any benefits in increased transfer rate. Note that you can configure the Virtual Server's request logs to record compression statistics, as described in Using a Custom Format String on page 167. Note that the user will not be aware whether your Virtual Server's web site is using content compression. The only thing that they may be aware of is a change in response times. Web site content is made up of different types of files (indicated by MIME type, as described in Configuring MIME Types on page 105), and each file can either be static or dynamic (as described in Web Server Functionality on page 28). You can configure which MIME types the Virtual Server compresses and whether it compresses static and/or dynamic files independently. The following sections describe how to do this. Configuring which MIME types to Compress The effectiveness of file compression can be measured by the ratio of its compressed file size to its uncompressed size. This can vary according to what type of file it is. For example, text files typically achieve a good compression ratio. On the other hand, many image files, which are already compressed, do not.! Specify which types of file the Virtual Server should compress by specifying a list of MIME types to be compressed. The recommended defaults are text/html and text/plain files 36. Warning: Some browsers (such as Netscape Communicator 4.x) are unable to handle some compressed file types correctly. It is therefore strongly recommended 36. Text compresses very well, typically reducing to about 10% of original size. However, other file types (e.g. compressed graphics files like JPEG) should not generally be compressed. Configuring File Handling 121

124 that you do not compress content with a MIME type of text/css or application/x-javascript. 1) Add MIME types to the list by selecting each from the dropdown box, or typing it directly into the text box. 2) Click the Apply changes button. Zeus Web Server adds the MIME type to the list. To remove one or more MIME types from the list, set the check box in the Delete column and click the Apply changes button. Configuring Static Content Compression Static content are files in your document root that are served without modification. This means that the Virtual Server only compresses the file the first time that it is requested. The compressed version of the file is then cached and returned immediately when any further requests for this file are received from a browser that supports compression. If the file is updated after a compressed copy has been cached, the updated file is re-compressed and replaces the existing compressed file in the cache. Files in your document root that can change for each request (e.g. if they include Server Side Includes) are dynamic not static content. In general, static files are compressed on web sites that have slower links. To configure static content compression, do the following: 1) Click the Compress static content radio button. 2) Specify the full path of the location of the cache directory. This is the directory in which all the compressed files are stored. This can include the %docroot% and %zeushome% variables, which the Virtual Server expands in the usual way. If this directory does not exist, then it is created when the Virtual Server is started. The permissions on this directory will only allow access by the user that the web server is configured to run as. 3) Specify the minimum size of the files that are to be compressed, in bytes. Compressing very small files offers little benefit as the time taken to 122 Configuring File Handling

125 access and return the cached file, and for the browser to uncompress it, will outweigh the small gain in transfer time. 4) Specify the maximum size of the files that are to be compressed, in bytes. In general web sites should be designed so that the most commonly accessed files are relatively small. Very large files are therefore less likely to be requested (and so there is less benefit in caching them) and they can fill the cache. Set this field to zero to specify an unlimited maximum file size. Configuring Dynamic Content Compression Dynamic content changes every time it is requested. Any URL requested from the server that is not a static file is classed as dynamic content (for example, CGI, FastCGI, ISAPI, NSAPI or other programs which generate content. Note that Server Side Include (SSI) pages cannot be dynamically compressed). This means that the web server must compress the generated file each time it is requested, and cannot cache them. In general, dynamic files are only compressed on text intensive web sites that are running on fast machines with limited bandwidth, or serving pages to users on slow links. To configure dynamic content compression, click the Compress dynamic content radio button. 7.5 Configuring File Uploading If you want users to be able to upload files to your web site using the HTTP/1.1 PUT method, enable the file uploading functionality. Typically, the PUT method is used by applications such as web publishing tools to let users upload files to the web site. Controlling Security You can use the PUT method more securely by requiring users to enter their name and password before they can upload a file, or by only allowing files to be uploaded from certain computers. This can be configured using the htaccess functionality, as described in Using htaccess Files on page 199. Configuring File Handling 123

126 Controlling File Ownership Normally, when a file is uploaded to the web site it becomes owned by the web server and the user no longer has any control over it. To enable users to maintain control over their files once they are uploaded, do the following: 1) Implement an access control mechanism to force users to enter their name and password before uploading files. This can be done in a number of different ways as described in Configuring Access on page ) In the Controlling File Ownership section of the File Uploading page, select the option Users maintain ownership of uploaded files. 124 Configuring File Handling

127 CHAPTER 8 Configuring URL Handling 8.1 Introduction Virtual Servers handle requests for files and directories, and return files to users. You can configure how each Virtual Server handles URLs in the following ways: To make files available on your web site that are outside the document tree, and to configure the Virtual Server to run a particular application (such as CGI, PHP, ISAPI, and so on) when a file in a particular subdirectory is requested, refer to Configuring URL Mapping on page 126. To configure some requests to be forwarded automatically to other web servers, refer to Configuring Gateway Aliases on page 129. To enable users to publish web pages in their own home directories, refer to Configuring Home Directories on page 132. To control what happens when a user requests a directory rather than a file, refer to Configuring Directory Requests on page 137. To configure Zeus Web Server to run a particular application (such as CGI, PHP, ISAPI, and so on) when a file with a particular file extension is requested, refer to Configuring Handlers on page 139. To configure request rewriting scripts, refer to Configuring Request Rewrite Scripts on page 140. You can configure each Virtual Server to provide basic spelling correction for all URLs entered for its web site. This can make it easier for users to find pages by avoiding case sensitivity in URLs and by correcting simple Configuring URL Handling 125

128 typos. This is described in more detail in Configuring Spelling Correction on page Configuring URL Mapping URL mapping enables you to map particular URLs (files and directories) to different locations or files. Each URL mapping is known as an alias. An aliased subdirectory is a directory that is configured to pass all requests for it to a specified directory or application. Use aliases to make directories located outside the document tree accessible. This enables you to keep applications (such as CGI scripts, FastCGI, or ISAPI applications) in protected directories, outside the document root, to ensure greater security for your web site. The alias makes the directory or file appear as if it is located in the document tree. It specifies the real location of the directory or file, and the place where you would like it to appear to be. The directory or file can then be accessed using a URL containing the alias. Use aliases to pass all requests for a particular directory to a specified application. 37 Creating an Alias By default, Zeus Web Server is configured with the /icons/ alias. This is used for the images in the default HTTP error pages (described in Error Handling on page 173). To add a new alias to simply make directories or files appear to be in a different location, do the following: 1) Access the URL mappings page by clicking the URL Mappings link in the configuration page menu. 2) In the Adding a Directory Alias section, specify which requests you want the alias to map. This is the location where you want the directory or file 37.Refer to Configuring Handlers on page 139 to see how to map requests for files with a particular file extension to a specified application. 126 Configuring URL Handling

129 to appear under the document root- that is, the location that users will specify in a URL. If you are creating an alias to a directory, then the Docroot Path should end with a /. 3) Specify the actual location to map the requests to. This can be expressed in either of the following ways: As an absolute path, for example, /sales/pricelist/ As a path relative to the Zeus Web Server installation directory. To do this, use %zeushome% to represent the installation directory, for example, %zeushome%/web/etc/icons/. 4) Click the Apply changes button. For example, if you have a directory called /sales/pricelist/ and you want it to appear on your web site as then create an alias as follows: Requests for... /prices/ Are mapped to... /sales/pricelist/! Warning: If the entry in the Docroot Path does not end in a / character then it is treated as a wildcard, and matches any file or directory that starts with the same characters as it. In the example above, if you map requests for /prices to /sales/pricelist, then a request for actually returns the file /sales/pricelist.html. This type of alias should be used with caution, because it could enable users to request files that are not explicitly linked to in your web pages (and which you do not intend users to see), but are simply present in a directory in the document root. Configuring URL Handling 127

130 i Note: Aliases of this type should be used with caution, You can also set up aliases for specific types of programs in the following way: For more information about setting up aliases for CGI scripts, refer to Configuring Aliases for CGI Script Directories on page 216. For more information about setting up aliases that are used by FastCGI responders, refer to Configuring Local Responder Script Directories on page 230. For more information about setting up aliases for ISAPI modules, refer to Configuring ISAPI Extension Directories on page 240. Deleting an Alias This page displays all the URL mappings in the system. Some types of mappings can be deleted from this page (indicated by having a delete check box). To delete an alias from the list of mappings, do the following: 1) Click the Delete check box to the right of the alias. 2) Click the Apply changes button. i Note: Other types of URL mappings cannot be deleted directly from this page. If a mapping does not have a check box beside it, then access its configuration information by clicking the link in the Type column. This takes you to the user interface page on which the mapping was configured. View the page s online documentation for more information about removing the mapping. Editing an Alias Once an alias has been configured, it is possible to change the location that requests are mapped to. To do this, edit the value directly in the table of aliases, then click the Apply changes button. Values that cannot be changed are displayed as text, and not text boxes. To change which requests are mapped using an alias, delete the alias and create a new one from the appropriate page. 128 Configuring URL Handling

131 8.3 Configuring Gateway Aliases You can forward requests for certain parts of your web site to another web site, which can be on a different server, by using the gateway aliases functionality. This is useful if you have a legacy web server and want to integrate its content into a new web site, but leave some applications or HTML files in their original locations. Gateway aliases enable users to request files from the new web server, and receive them as if they were on the new server, when they are still located on the legacy server. To the user, the files appear to be located on the new server. The web server that requests are forwarded to is called the origin server. The gateway aliases functionality enables you to forward requests for various parts of your web site, including requests for individual files, entire directories, or file names that match a certain pattern. The original URL can be preserved or changed before it is forwarded to the specified web server (see Rewriting the URL before forwarding on page 132). All other data in the HTTP request is preserved and forwarded. You can configure any number of gateway aliases. Each one specifies the requests that should be forwarded, and the name of the origin server to which they should be forwarded. You can specify the requests to forward in any of the following ways: File name, such as /docs/page1.html. Directory, such as /docs. A request for any file in this directory is forwarded. Regular expression, such as ~.*\.html$. A request for any file matching this regular expression is forwarded. Note that you identify regular expressions by prefixing them with a ~. For details on using regular expressions, see Using Regular Expressions on page 389. For example, if the /news/ directory is configured to be forwarded to the web server then Zeus Web Server forwards a request for to Configuring URL Handling 129

132 i Note: If a request matches more than one gateway alias, it is forwarded to the most specific one, that is, the one with the longest matching directory path. Adding a Gateway Alias To add a new gateway alias, do the following: 1) Access the gateway aliases page by clicking the Gateway link in the configuration page menu. 2) Enable the Virtual Server s gateway functionality by clicking the appropriate radio button. 3) In the Adding a Gateway Alias section, specify the file name, directory or regular expression for the requests that should be forwarded. If you specify a directory name then it must be relative to the Virtual Server s document root. 4) Enter the host name and port number of the web server that requests should be forwarded to. 5) Click the Apply changes button. The new gateway alias is added to the list of existing aliases. It is not used until you commit the new configuration, at which point it is checked for validity. If the origin web server does not exist, the rule is ignored. If the origin server does exist, but for some reason is not available when a request is forwarded to it, the HTTP error code 502 ( Bad Gateway ) is returned. Rewriting HTTP Redirects The origin server may issue an HTTP redirect to a different URL in the form of a Location header. If the URL is absolute (i.e. it refers directly to a URL on the origin server), it is often necessary to replace the name of the origin server with the name of the gateway server. For example, the origin server may be behind a firewall and not be directly accessible. This option will replace the name of the origin web server with the name of the gateway in redirects issued by the origin server. You should 130 Configuring URL Handling

133 select the Yes radio button to rewrite these HTTP redirects to refer to the gateway server, or the No button to leave HTTP redirects un-altered. Rewriting HTTP Cookies The origin server may attempt to send a cookie (page 394) to the client browser. A cookie can optionally have a domain parameter, which specifies which web site domains the cookie should be sent to. The optional domain in the cookie must match the domain of the web site that the client is currently accessing, of client software will not accept it. For example, if the client is accessing the cookie domain must be either or.example.com (top-level.com domains are not allowed). Set the Rewrite cookies option to Yes if you would like to automatically rewrite all cookie domains that are not within the current web site domain. This option sets the cookie domain to the current web site domain, removing the first part of the domain if possible. In the above example, if the origin server set a cookie for the domain internal.hosting.com, it would rewrite the domain to.example.com. Deleting a Gateway Alias To delete a gateway alias, do the following: 1) Click the Delete check box next to the alias that you want to delete. 2) Click the Apply changes button. The gateway alias is removed from the list of aliases. Changing a Gateway Alias To change the host name server and port of a gateway alias: 1) Edit the host name and port number directly in the list of aliases. 2) Click the Apply changes button. Configuring URL Handling 131

134 i Note: It is not possible to edit the part of the gateway alias specifying which requests to forward. To do this, delete the gateway alias and create a new one. Rewriting the URL before forwarding The original URL can be changed before it is forwarded by the gateway alias, by using the Request Rewriting functionality to change the URL. It can also be changed by using one of the web server programming APIs (for example, ISAPI or NSAPI). This makes it possible to forward requests for one location on the gateway server to a different location on the origin server. For example, requests for /sales on the gateway server may be forwarded to /sales_us on the origin server. For more details on request rewriting, see Configuring Request Rewrite Scripts on page Configuring Home Directories To enable users of the server running your web site to be able to publish web pages in their own home directories, use the home directories functionality. When this is enabled, Zeus Web Server makes the configured public_html subdirectory of a user s home directory available on the web site in a ~username directory under the document root. For example, when a user requests the URL they receive the file index.html from the directory /home/username/public_html. Changing the Web Page Subdirectory By default, users must publish their web pages in the public_html subdirectory of their home directories. To configure Zeus Web Server to use a different subdirectory, do the following: 1) Access the home directories page by clicking the Home Directories link in the configuration page menu. 132 Configuring URL Handling

135 2) In the Mapping Usernames to Home Directories section, enter the new directory in the Web page subdirectory field. 3) Click the Apply changes button. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Changing the Username Prefix If you do not want to use the ~ character as a prefix to indicate a username, you can configure any other text string to be used instead. The following table shows some example prefixes, and the resulting URLs required to access the home directories: Username Prefix blank user_ users/ URL of home directories To change the username prefix, do the following: 1) Access the home directories page from the configuration page menu. 2) In the Mapping Usernames to Home Directories section, enter the new username prefix. 3) Click the Apply changes button. For this change to take effect, commit the new configuration to the Virtual Server. Configuring Username to Home Directory Mapping Zeus Web Server handles requests for URLs containing usernames by looking up the user to find their associated home directory and then mapping this URL to the public_html subdirectory within it. Configuring URL Handling 133

136 By default, Zeus Web Server maps ~username URLs to users home directories using the standard Unix user lookup service 38. There are other ways to configure how this mapping is performed. They are: By using the standard Unix passwd file. By using a file in the same format as the passwd file. By treating all home directories as subdirectories in one location. By using an LDAP server. These are described in more detail below. Using the Standard passwd File To configure Zeus Web Server to locate a user s home directory using the standard Unix /etc/passwd file, do the following: 1) Configure your operating system s user lookup service to use the /etc/passwd file. For information on how to do this, consult your operating system s documentation. 2) Access the home directories page from the configuration page menu, and select Use the operating system user-lookup service. 3) Click the Apply changes button. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Using a File Similar to /etc/passwd To configure Zeus Web Server to locate a user s home directory using a file in the same format as the standard Unix passwd file, do the following: 1) Create a text file containing one line for each user, where each line contains the following fields: username:x:x:x:x:homedir:x (x indicates data that is ignored by Zeus Web Server.) 38.This is configured within the operating system, in the file /etc/nsswitch.conf. 134 Configuring URL Handling

137 2) Access the home directories page from the configuration page menu, and select Use a file similar to /etc/passwd. 3) Click the Apply changes button. 4) In the Using a File Similar to /etc/passwd section, enter the full path to the text file. 5) Click the Apply changes button again. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. If All Home Directories are in a Single Subdirectory If all your users home directories are subdirectories of a particular directory then there is no need to look up the location of each home directory in a file. In this case, do the following: 1) Access the home directories page from the configuration page menu, and select All home directories are in one subdirectory. 2) Click the Apply changes button. 3) In the Configuring the Location of the Home Directories section, enter the full path of the directory that contains all the home directories. For example, if you set the home directory path to /usr/web/, then users can publish their web pages in /usr/web/username/public_html. 4) Click the Apply changes button again. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Using an LDAP Server An LDAP server is an external server that uses the Lightweight Directory Access Protocol to provide directory services. If you have a large number of users whose details are stored using an LDAP server, then you can use it to map between URLs and the users home directories. You should only use this option if you are familiar with LDAP. Configuring URL Handling 135

138 To configure Zeus Web Server to use your LDAP server, do the following: 1) Access the home directories page from the configuration page menu, and select Using an LDAP server. 2) Click the Apply changes button and the page is expanded to reveal the Using an LDAP Server section. 3) Enter the LDAP authentication details. If your LDAP server requires its clients to be authenticated, you must tell Zeus Web Server how to authenticate itself when it contacts the LDAP server. LDAP authentication is composed of two parts, a Binddn and a password, which can be obtained from your LDAP server administrator. Enter these in the fields in the Authentication section. 4) Set the LDAP URL. Specify the LDAP URL that Zeus Web Server uses to query the LDAP server. This URL must be in the form of a query that passes a username to the LDAP server and requests the name of the corresponding home directory. When entering the LDAP URL, replace the actual username with $u. This symbol is converted into the appropriate username when the query is sent to the LDAP server. For example, the following LDAP URL queries the LDAP server located at ldap.myserver.com, and asks for the homedir attribute of the required user: ldap://ldap.myserver.com/o=zeus?homedir?sub?cn=$u The section cn=$u is replaced by cn=username when the query is sent to the LDAP server. 5) Optionally, set the second LDAP URL. If your LDAP server requires two URL queries to resolve a username to a home directory, enter the second URL here. The second query uses the results produced by the first one. For example, if the first URL resolves the username to a user number, then the second URL could resolve the user number to the user s home directory. You can use an additional symbol, $r, inside the second LDAP URL. At the point when the second query is performed, this symbol is replaced by the 136 Configuring URL Handling

139 result of the first query. You can also use the symbol $u, which is replaced by the username. 6) Set the Cache Timeout value. Zeus Web Server uses a cache to improve query times and reduce the load on the LDAP server. The cache is simply a way of storing copies of all queries that are sent and the results they produced, for a certain period of time. Each time Zeus Web Server queries the LDAP server it stores the results in the cache. If the query needs to be performed again later, while the previous results are still in the cache, Zeus Web Server can simply use the results from before, rather than performing the query again. Results are held in the cache for a specified time period, called the Cache Timeout value, which is measured in seconds. 7) To save the new LDAP configuration, click the Apply changes button. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. i Note: Increasing the Cache Timeout value can improve performance by reducing the number of queries to the LDAP server. However, it also increases the risk that out of date information will be returned from the cache. This only becomes a problem if the data in the LDAP server is being updated frequently. 8.5 Configuring Directory Requests You can configure what happens when a user requests a directory (rather than a specific file), by using the directory requests functionality. Use this to: Configure a default page which is returned when a user requests a directory. This is known as the index file. See Configuring Index Files on page 138 for details. Enable users to see a directory listing if they request a directory that has no index file. See Configuring Directory Listings on page 138 for details. Configuring URL Handling 137

140 Configuring Index Files The Index Files section of the directory requests configuration page lists the index file names that Zeus Web Server looks for when the user requests a directory 39. For example, if the index file name is set to index.html, then when a user requests the URL they receive the file index.html from the document root directory. Some types of index files such as index.jsp or index.php are handled by configuring the application associated with them. Refer to the application s documentation for more information about this. You can modify the list of index file names as follows: To add a new index file name to this list, do the following: a) Access the directory requests page by clicking the Directory Requests link in the configuration page menu. b) Enter your index file name in the index filename field. c) If you use various index file names on your system, enter them all, separated by commas. Remove unwanted file names by simply deleting them from the list. This is recommended because when a user requests a directory, Zeus Web Server looks for each of the listed index file names in turn. This means that if you have a long list of index file names, it may take longer to respond to directory requests. Configuring Directory Listings To enable users to see a directory listing if they enter the name of a directory that has no index file, enable the Directory Listing section. The user then receives a page containing a list of all the files in the directory, with links to each of the files. 39.Directory requests generally end with a / character. 138 Configuring URL Handling

141 Zeus Web Server can generate several different styles of directory listing. Select the style that you would like to use from the list in the Directory Listing section. Changing the Directory Listing using htaccess. An htaccess file can be used in on a per-directory basis to control which files can be used as index files, and which files are excluded from a directory listing if an suitable index file cannot be found. For information on doing this, see Using htaccess Files on page 199 and Directory Listing Directives on page Configuring Handlers Many third party applications, such as CGI or PHP, operate by processing the requested file and generating an output file that is returned to the browser. To tell the Virtual Server which application processes which type of file, configure the handlers functionality. A handler passes the specified file requests to the associated application, which processes them and returns the results to the user 40. Adding a New Handler To add a new handler, do the following: 1) Access the handlers page by clicking the Handlers link in the configuration page menu. 2) Specify the file extension of the files that the handler should pass to the application in the file extension field. Note that this should not contain the leading dot. 3) Specify the location of the handler application itself. This should be entered as a path relative to the document root. 4) Specify whether the handler is able to handle HTTP 404 File not found errors. By default, handlers are responsible for handling these, but you 40. Refer to Configuring URL Mapping on page 126 to see how to map requests for files in a particular subdirectory to a specified application. Configuring URL Handling 139

142 can configure the Virtual Server to handle them instead. In this case, if the handler (such as PHP) is unable to find the input file, it returns the error to the Virtual Server, which displays the associated HTTP error page. For information about configuring HTTP error pages, refer to Error Handling on page ) Click the Apply changes button. i For example, if you want to add a new handler for PHP scripts, set the file extension to php and enter the location of the PHP application handler. If the PHP handler is configured as /fcgi-bin/php.fcgi, then a request for /sales/index.php is passed to /fcgi-bin/php.fcgi/sales/index.php. This runs the /fcgi-bin/php.fcgi application and passes the part of the URL following the handler element (in this case, /sales/index.php ) to the application in the PATH_INFO environment variable. Similarly, it sets the PATH_TRANSLATED environment variable to docroot/sales/index.php. Note: Handlers for ISAPI applications must also be located in a directory that has been configured as an alias. For details on how to do this, see Configuring URL Mapping on page Configuring Request Rewrite Scripts The request rewriting functionality can be used to change a requested URL into any other URL by running a script of rewrite commands to pre-process every request. This powerful functionality enables you to modify the URL and HTTP headers of a request in any way you want. The modified request is passed on to be processed in the usual way, returning the requested page to the user. This process is transparent to the user; they received the page that they requested. 140 Configuring URL Handling

143 This powerful functionality can be used in many different ways. It is typically used to: Prevent broken links when a URL on your web site becomes obsolete. You may restructure a web site, moving commonly accessed files that users may have bookmarked. The rewrite scripts can change requests for the files from their old locations into requests for the files from their new locations. Store cookie information in URLs. Cookies are useful for tracking a user s visits to a web site, but are easily disabled by users, making them ineffective. The request rewriting functionality can be used to effectively hide cookie-style information in URLs, enabling you to track users even if they have disabled cookies. Hide the implementation details of your web site. Some parts of your web site may only be available via lengthy or complicated URLs. The rewrite functionality can enable users to access these parts of your web site using much simpler URLs. Convert from an existing Apache web server that uses mod_rewrite. If you have an Apache web server that uses mod_rewrite scripts, you can convert these to run on Zeus Web Server. Some example request rewrite scripts can be found in the API Examples and Documentation section, at: Using Request Rewrite Scripts To use the request rewriting functionality, create a script in the Zeus Request Rewrite Scripting Language. The script contains instructions telling the Virtual Server how to change the URL or headers of requests that match specified criteria. The Virtual Server compiles the script, and (if the rewrite functionality is enabled) uses it every time it receives a request. It runs the commands in the script, changing the URL if it matches the specified criteria. Once the script is finished, the Virtual Server continues processing the resulting URL. Configuring URL Handling 141

144 When changing the URL, the rewrite functionality can only change the local part of it, that is, the part of the URL after the host name. For example, if a user requests the rewrite functionality can only make changes to /sales/uk.html. This means that you cannot use the rewrite functionality to change the request to refer to a file on another Virtual Server. For example, the following script illustrates how to change requests for any HTML files in the /sales directory so that the user receives them from the /newsales directory instead: match URL into $ with ^/sales/(.*)\.html if matched set URL=/newsales/$1.html The rewrite functionality can also change the HTTP headers that were received with a request, and create new HTTP headers to be returned to the user. For example, the following script changes the HTTP host header, so that a request for is redirected to the Subserver match URL into $ with ^/([^/]+)/(.*)$ if matched then set IN:Host = set URL = /$2 endif Syntax of the Scripting Language Zeus Request Rewrite Scripting Language is a simple yet powerful language, enabling you to test whether certain patterns occur in a URL, and then change the URL in a specified way. Scripting instructions are composed of keywords, variables, strings and labels. The instructions in the script are run in order, starting from the beginning. Once the last instruction has been executed, the script ends. The script must have one command per line, with each keyword separated by spaces. The language is case-insensitive, but you are recommended to use lowercase for the keywords and uppercase for the variable names and labels, to make your script easier to read. 142 Configuring URL Handling

145 The following sections describe the component parts of the language, and how they are linked together. Scripting Language Variables Variables are used to hold strings. Some variables store a single string, but others are arrays, capable of storing multiple strings. For example, the variable URL can hold a single string, such as /index.html, but the variable SCRATCH: is an array, holding multiple strings. Each element of an array has its own name, so that, for example, the SCRATCH: variable could have two elements called SCRATCH:path and SCRATCH:file. i Note: All variables can have values assigned to them, but some variables cannot have their contents read. The following table shows all the variables that can be used in the script. Variables that can only have values assigned to them are marked as being Write Only Symbol Use Write Only URL REMOTE_HOST REMOTE_ADDR REMOTE_USER REQUEST_METHOD When the script starts, this variable holds the part of the requested URL after the host name. When the script ends, the final contents of this variable are used by the Virtual Server as the new request. This variable holds the hostname of the remote client, or the IP address if DNS was not enabled, or failed to return a record. This variable holds the IP address of the remote client. This variable holds the username of the remote user, if one was provided using an authentication method. This variable holds the request method (such as GET or POST ) of the request. This variable is read-only - you cannot change its value in a rewrite script. Configuring URL Handling 143

146 Symbol Use Write Only ENV: IN: OUT: SCRATCH: NOTES BODY RESPONSE An array of strings, containing the operating system environment variables. You can change the value of any of these strings, and add new ones. 1 An array of strings, containing the HTTP headers that were received with the request. An array of strings, containing the HTTP headers that will be returned to the user s browser when the request is completed 2. This array is initially empty. An array of strings that you can use to hold temporary values. The contents of this variable are lost when the script ends. An array of strings that you can use to store notes. These notes can be logged to a log file in a custom log format, allowing you to pass information through to further hooks without creating new HTTP headers. Some APIs such as the Zeus Perl Extensions can read notes variables too. Set with the content that is to be returned to the user s browser. After Zeus Web Server returns this, it closes the connection. Specifies the HTTP response code that it is to be returned, if BODY is set. See HTTP Status Codes on page Y Y Y 1. You can only assign a value to each individual element of the ENV: array once during the script. 2. You cannot assign a value to OUT:Server, OUT:Date or OUT:Connection, as these headers are reserved for use by the Virtual Server. 3. Reading from RESPONSE will return an undefined value unless you have written to it. It will not return the response code set by another part of the web server. 144 Configuring URL Handling

147 Scripting Example using Variables The following example looks for requests to Java Servlet pages (.jsp files) and returns a redirect to another virtual server running on port match URL into $ with ^/.+\.jsp if matched then match URL into $ with ^(.*)$ match IN:Host into % with ^(.*)$ set OUT:Location= set RESPONSE=301 set BODY=<a href=" here</a> endif The following sections in the documentation describe the match, if and set commands, as well as the other commands provided by the rewrite scripting language. Scripting Language Commands The following commands can be used within a request rewrite script: match command This command tests a variable to see if its contents match a specified pattern. The pattern is defined in terms of a regular expression. For more Configuring URL Handling 145

148 information about regular expressions, see Using Regular Expressions on page 389. Syntax: Parameters: [insensitive] match variable into array with regex insensitive Use this keyword if you do not want the match to distinguish between uppercase and lowercase letters. variable This can be any of the standard variables described in Scripting Language Variables on page 143. array regex This can be either of the special purpose arrays $ and %. A standard regular expression, as described in Using Regular Expressions on page 389. If the variable matches the regular expression, then the matched flag is set to true, otherwise it is set to false. This flag is used in subsequent if commands, to determine whether to execute a block of commands. Regular expressions can contain captures, which are subsections of the regular expression enclosed in round brackets. When a variable matches a regular expression containing captures, the parts of the variable that match the capture sections are stored in numbered elements of one of the special array variables, $ and %. For example, the following command contains a regular expression with two captures: match URL into $ with /(sales.*)/(.*)\.html If the URL is /sales2001/uk.html then this matches the regular expression and the subsections matching the captures are stored in the $ array as follows: $1 = sales2001 $2 = uk 146 Configuring URL Handling

149 if command This command tests the state of the matched flag to control whether a subsequent command (or group of commands) is executed. This flag is set to true or false by the most recent match command. This command can be used in two ways: Simple: Syntax: if [not] matched [then] command When using the simple syntax, the command is executed if the most recent match command was successful. If you use the not keyword, the command is executed if the most recent match failed. The then keyword is optional, and is included for readability only. Multi-line: Syntax: if [not] matched [then] command : : : command [else command : : : command ] endif When using the multi-line syntax, the first block of commands is executed if the most recent match command was successful, and the second (optional) block of commands is executed if the most recent match failed. If the not keyword is used, the first block of commands is executed if the most recent match command failed, and the second (optional) block of commands is executed if the most recent match was successful. The then keyword is optional, and is included for readability only. Configuring URL Handling 147

150 set command This command stores a string in a variable. Syntax: Parameters: variable The = operator simply stores the string in the variable, removing any previous value. For example, the following command stores the string /sales/index.html in the URL variable: set URL = /sales/index.html The. operator concatenates the string to the current contents of the variable. For example, the following commands store /sales/ in the URL, and then join index.html onto the end of it: set URL = /sales/ set URL. index.html set variable operator string operator string Any of the standard variables described in Scripting Language Variables on page 143. The following operators can be used: = The assignment operator.. The concatenate operator. Any string, as described in Scripting Language Strings on page Configuring URL Handling

151 goto command This command tells the rewrite script to jump to a named location in the script, and continue running from there. Syntax: goto label Parameters: label Any label, as described in Scripting Language Labels on page 153.! Note that when labels are used in a goto command, they do not have a trailing : character. For example: goto MY_LABEL Warning: The goto command should be used with caution, because it is possible to create a script that will never finish if a goto jumps to a label earlier in the script. If a script becomes stuck in this kind of loop, the Virtual Server will eventually detect it, and stop the script. For more information about this, see Stopping a Script in a Loop on page 158. map command This command tells the rewrite script to map the specified expression into either a filesystem path or a MIME type. Syntax: map (path mime) into var from path Parameters: var The variable to be written into path A path to a file relative to the document root The parameter should be a path to a file relative to the document root and the variable should be writable. If the path is requested, then the absolute path to the file will be written to the variable. If the MIME type is requested, then the MIME type for the file will be written to the variable. The variable will be set to the empty string if the mapping fails for any Configuring URL Handling 149

152 reason. The map path command works with subservers and can be used to determine the document root for a subserver enabled Virtual Server. For example: # To get the document root for the vserver map path into SCRATCH:docroot from / # To find out the mimetype for a.class file map mime into SCRATCH:docroot from /dummy.class look command This command tells the rewrite script to look for the file or directory specified. Syntax: look for (dir file) at path Parameters: dir Look for a directory at the specified location file Look for a file at the specified location path The path specifies the location to look at. If the specified entry exists and its type matches the specified 'dir' or 'file' then the condition 'exists' is set. Otherwise the condition 'not exists' is set. For example, for the following script allows one to customize behaviour if a file is not found: map path into SCRATCH:path from %{URL} look for file at %{SCRATCH:path} if not exists then look for file at %{SCRATCH:path}/index.html if exists then # Serve content and do things here else # Provide custom "Not found" message to user endif 150 Configuring URL Handling

153 i Note: These conditions invalidate the use of 'matched' and 'not matched' until the next 'match' instruction. The next 'match' instruction will invalidate the use of 'exists' and 'not exists' until the next 'look for'. execute command This command tells the rewrite script to suspend execution of the current script, and run the script specified in the expansion string given as the argument to the execute command. Syntax: execute script Parameters: script The path to the script to execute. If the file could not be found, or was not compilable, then execution continues from the next instruction. Use 'look for file at' if you wish to check for the file existing before running it. Any compiler errors will show up in the virtual server error log. For example: i map path into SCRATCH:docroot from / look for file in %{SCRATCH:docroot}/../rewrite.script if exists then execute %{SCRATCH:docroot}/../rewrite.script endif Note: The sub-executed scripts share the SCRATCH: namespace, and all captures in $1-9 and %1-9. This allows you to pass parameters to and from the subscripts but you should be aware that the values in those variables should not be trusted post-execution. Configuring URL Handling 151

154 restart command Syntax: Parameters: restart none This command tells the rewrite script to return from the currently executing script (unwinding all running scripts on the stack) and restart the connection. It does not take any parameters. Restarting the connection may cause it to be handled by a new Virtual Server. However, a new Virtual Server can only be found on the same IP and port number combination as the original Virtual Server. For example: # Make this a different virtual server handle this request set IN:Host = restart substr command Syntax: substr dest is src from startpos for num Parameters: dest The variable data is copied to src The variable data is copied from startpos The start position to start copying from num Number of characters to be copied This command tells the rewrite script to take a portion of a variable (the source) and write it into another variable (the destination). This is a substring operation. The command takes a character start position in the variable and the number of characters of the variable to be copied. For example: # Copy the three characters from IN:Host to My variable substr SCRATCH:My is IN:Host from 1 for Configuring URL Handling

155 Scripting Language Labels A label is a marker in the script, and does not perform any action. Labels are used as the destination for goto commands. Labels can be used anywhere in a script, but must be on a line by themselves. A label is a string of text ending in a colon, and composed of uppercase and lowercase letters, numbers, underscore characters and hyphen characters. For example, the following are valid labels: MY_LABEL: SECTION1-5: There are two hidden labels that are automatically included in the script, and can be used in goto commands. These are: BEGIN: This label is located at the start of the script. END: This label is located at the end of the script. i Using the command goto END makes the script finish. Note: It is not possible to define your own labels called BEGIN: or END:. Scripting Language Strings A string is composed of any number of letters, numbers, symbol characters and spaces. The following are examples of valid strings: This is a string. /sales/usa/index.html Variables can be included in strings by identifying them with the %{} code. For example, if the variable SCRATCH:path contains sales, then the string /root/%{scratch:path}/index.html has the value /root/sales/index.html. To include elements of the special array variables $ and % in a string, simply use them directly. For example: Configuring URL Handling 153

156 /root/$1/index.html Scripting Language Comments Any line of the script starting with a # character is a comment line, and is ignored by the compiler. For example: # This is a comment Nesting Commands in Scripts if statements can be nested within each other to any depth: match URL into $ with a if matched match URL into $ with b if matched set URL = /yes_a_yes_b.html else set URL = /yes_a_not_b.html endif else match URL into $ with b if matched set URL = /not_a_yes_b.html else set URL = /not_a_not_b.html endif endif Developing Request Rewrite Scripts When creating and testing a request rewrite script it is important to isolate its functionality from any interactions with other Zeus Web Server functionality. When developing a script, you are recommended to: 1) Develop the script on a dummy Virtual Server, not a live one. 2) Disable all other functionality that could potentially interfere with your script. This includes spelling correction, aliases, and content negotiation. 154 Configuring URL Handling

157 3) Turn on compiler errors and debugging information. For information on how to do this, see Configuring Compiler Information on page 157 and Configuring Debugging Information on page 157. Once the script is running correctly, you can turn the other functionality back on. You are not recommended to use debugging information on a live system, as it significantly reduces performance. When writing a request rewrite script, it is important to bear in mind the following: The rewrite script operates on the URL before any of the other Zeus Web Server functionality. This means that the script receives the URL exactly as the user requested it. Other functionality operates on the URL that is output from your script. While rewrite scripts can be used to implement the same behavior as other Zeus Web Server functionality (such as aliases), it is recommended that you use the dedicated functionality as this will be more efficient and effective. Make sure that the contents of the URL variable starts with a / character when your script finishes. If it does not, users will receive the HTTP error code 400 ( Bad Request ) in response to requests. Entering a Request Rewriting Script To create a request rewrite script for a Virtual Server, do the following: 1) Access the request rewriting page by clicking the Request Rewriting link in the configuration page menu. 2) Enable request rewriting functionality by clicking the appropriate radio button. 3) Enter your script into the Rewrite Script edit box. 4) Click the Apply changes button. 5) Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. The Virtual Server compiles the script and starts using it. Configuring URL Handling 155

158 Running a Script The request rewrite script runs every time the Virtual Server receives a request. Therefore, if a user requests an HTML page with embedded image files, the script runs once for the HTML page and once for each image file. For this reason, request rewrite scripts should be kept as short as possible, to minimize the load placed on the Virtual Server. Debugging Scripts When implementing a script, you need to ensure that both its syntax and logic are correct. You can check these in the following ways: Compile the script. To compile the script, enter it into the request rewriting page and click the Apply changes button. The compiler compiles the script and reports any incorrect syntax it finds, categorized using one of the following prefixes: SERIOUS: An error of this type is so severe that the compiler cannot compile the script, and therefore URL rewriting cannot take place. Incorrect syntax is the most common cause of this type of error. WARN: An error of this type indicates that you have written a script with correct syntax that contains something that may be a mistake. This happens, for example, if you define a label but never use it. The Virtual Server is still able to compile and run the script. INFO: This does not indicate an error, but merely reports information from the compiler. Run the script. If your script has correct syntax but contains logical errors, it may make incorrect changes to URLs. The rewrite script enables you to check what is happening during the running of a script by recording debugging infor- 156 Configuring URL Handling

159 mation in the Virtual Server s error log file. The following information is included: When the script starts, the Virtual Server records the total number of commands in the script. This is the total of all the lines in the script, excluding comments, blank lines, labels and endif commands. Each time a match command is executed, the Virtual Server records whether the match was successful or not. If the matched regular expression contains captures, the matched sections are listed. When the script finishes, the Virtual Server records the total number of commands executed. Configuring Compiler Information To configure how much information is produced by the compiler, do the following: 1) Access the request rewriting page by clicking the Request Rewriting link in the configuration page menu. 2) In the Configuring Compiler Information section, select whether you want to see all the output from the compiler, including information and warning messages, or only the serious errors. 3) Click the Apply changes button. Configuring Debugging Information To configure whether script debugging information is produced in the Virtual Server s error log file, do the following: 1) Access the request rewriting page by clicking the Request Rewriting link in the configuration page menu. 2) In the Configuring Debugging Information section, select whether you want run-time debugging output to be produced. 3) Click the Apply changes button. Configuring URL Handling 157

160 Overwriting the Request URI Setting this option enables the request rewrite script to actually modify the original request URI. When this is done, the original URI is replaced with the rewritten URI throughout the request processing - although it is the original URI that is logged 41. i Note: Only do this if the Virtual Server is running an external application that uses the REQUEST_URI environment variable rather than PATH_INFO. To configure whether the request URI should be rewritten, do the following: 1) Access the request rewriting page by clicking the Request Rewriting link in the configuration page menu. 2) In the Overwriting the Request URI section, select whether you want to overwrite it or not. 3) Click the Apply changes button. Stopping a Script in a Loop It is possible for a request rewriting script to get stuck in a loop if you use a goto command that jumps to a label earlier in the script. If this happens, Zeus Web Server detects that the script is stuck in a loop, and stops it. It can do this because it counts the number of commands that a script executes each time it runs. If this number exceeds a certain value, Zeus Web Server assumes that the script is stuck in a loop, and stops it. A warning message is created in the error log file, and an HTTP error 500 ( Internal Server Error ) is returned to the user. To configure the maximum number of commands that a script can execute, do the following: 1) Go to the Stopping the Script if it is Stuck in a Loop section of the Request Rewriting configuration page. 41. Note, however, that if the rewrite script changes headers then it is these changed headers that are logged, and not the originals. 158 Configuring URL Handling

161 2) Enter the maximum value. 3) Click the Apply changes button. Commit your changes to the Virtual Server for this new value to take effect. Converting from Existing Apache mod_rewrite Scripts To automatically convert existing Apache mod_rewrite rules into a Zeus request rewrite script, do the following: 1) Go to the Converting Existing Apache mod_rewrite Rules section of the Request Rewriting configuration page. 2) Click the Convert existing rules link to go to the Converting Existing Apache mod_rewrite Rules page. 3) Enter your existing Apache rules into the edit box. 4) Click the Convert These Rules button. The equivalent Zeus request rewriting script is displayed. To use this script on your Virtual Server, click the Apply changes button. Zeus Web Server is able to convert the most common Apache mod_rewrite rules into Zeus Request Rewrite Scripting Language. If it encounters any problems during the conversion, it reports these along with the resulting script. 8.8 Configuring Spelling Correction To automatically correct simple errors in requested URLs, use the spelling correction functionality. This can correct the following types of mistakes: URLs that contain letters in the wrong case, for example, instead of This type of mistake Configuring URL Handling 159

162 commonly occurs with users of case-insensitive operating systems such as Windows. URLs that contain simple spelling mistakes, for example, instead of Spelling correction only attempts to correct mistakes in the last section of the URL, after the final / character. This means that URLs such as will not be corrected.! If Zeus Web Server finds a file that closely matches the requested URL, it automatically redirects the user s browser to this web page. If Zeus Web Server is unable to find a close match, it returns the HTTP error code 404 ( Not found ). Warning: If you have web pages in your document root that you do not want users to view, and that you have not linked to other pages, do not use the spelling correction functionality. If you do, an incorrect URL could be redirected to one of these hidden documents. Configuring the Spelling Correction Functionality To configure a Virtual Server to use the spelling correction functionality, do the following: 1) Access the spelling correction page by clicking the Spelling Correction link in the configuration page menu. 2) Enable the Virtual Server s spelling correction functionality by clicking the appropriate radio button. 3) Select whether you want Zeus Web Server to only correct case problems in URLs, or to correct case problems and simple spelling mistakes. 4) Click the Apply changes button. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page Configuring URL Handling

163 ! Warning: Always design web site content with the spelling correction functionality switched off, otherwise you may not notice spelling mistakes in URLs as you create them. Each time the spelling correction functionality encounters a spelling mistake, it examines all the file names in a directory to see if any of them are a close match to the incorrectly entered URL. The extra processing required to do this results in decreased performance on your web server. 8.9 Configuring Response Headers An HTTP response contains the body of the document that is returned - a web page, image or other resource. It also contains a number of HTTP Headers. Zeus Web Server sets the essential headers automatically - headers like the MIME type for example. Other ZWS modules can insert headers as appropriate - for example, the content compression module adds certain control headers to inform the remote client that the content is compressed. The.htaccess module (page 199 and page 325) and the majority of the dynamic APIs can also add or modify response headers. Sometimes, you may want to add some simple headers without wanting the complexity of.htaccess or a dynamic application. Common headers that you may want to configure this way include the Expires header, and the Cache-Control and Pragma headers. The Response Headers module allows you to do this. Configuring the Response Headers Functionality To configure a Virtual Server to use the response headers functionality, do the following: 1) Access the Response Headers page by clicking the Response Headers link in the configuration page menu. 2) Enable the Virtual Server s response headers functionality by clicking the appropriate radio button. Configuring URL Handling 161

164 3) Specify which requests you would like to add response headers to, and the response headers you would like to add. You can specify a request by the mime type of the response, or by a match on the path part of the URL requested. 4) Click the Apply changes button. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Response Headers example Suppose you wished to ensure that documents in the /secure part of your web site were never cached by client software. The usual way to achieve this reliably for all client software is to add three headers to the response. In the URL Path or Regex field on the Response Headers page, enter the following value: /secure In the Response Headers box, enter the following text: Pragma: no-cache Cache-Control: no-cache Expires: %{-7d}t This will cause all responses to requests for files under /secure to include these three headers. The Expires header will contain a date of one week ago. Response Headers macros The Response Headers module allows you to use macros in the value of the headers. The following macros are supported: Macro: Meaning %h The hostname of the web server machine. %d The domainname of the web server machine. %p The process id of the web server child process. %c The child id (1 to n) of the child process. 162 Configuring URL Handling

165 Macro: Meaning %v The name of the virtual server that responded to the request. %i A fixed-width counter value; starting at 0 and incrementing by 1, this counter returns a different value for each use and wraps at 2^32. Note that multiple child processes may generate the same counter value, and the counter resets to 0 if a child process restarts. If you want a unique value in an SMP environment, you may wish to use the macro %p%i ; in a clustered environment, you can use %h%p%i. %t The current time, in HTTP Expires format. %m The last-modified time of the requested resource, in HTTP Expires format. If the resource is not available (for example, it is mapped to a remote gateway), the current time is returned. The %t and %m macros additionally support an offset value, giving the offset from the time they calculate. The offset is a list of <count><type>, where <type> specifies the time unit of the offset: seconds, minutes, hours, days, weeks, Months and years: Time value: Meaning %t The current time. %{1w}t One week in the future. %{-10d}t 10 days ago. %{1h30m}t 90 minutes in the future. %{24h-1s}t Almost 24 hours in the future. %{3M}t 3 months in the future. %{1y}t Next year Configuring URL Handling 163

166 Example: Setting an Expires time for images Typically, images on a web site do not change often, but make up a considerable part of the bandwidth when a page is downloaded. If client software is informed that the images change infrequently, it can cache them for extended periods of time, thus reducing the bandwidth used and improving the download time of the page. The following configuration sets the expiry time for all images to be 30 days in the future: Mime type: Response Header: image/* Expires: %{30d}t 164 Configuring URL Handling

167 CHAPTER 9 Configuring Logging and Monitoring 9.1 Introduction Zeus Web Server enables you to monitor the performance of your web sites, and track how people are using them. It enables you to: Configure how web site requests are logged (see Configuring Request logging on page 165). Configure how the web site handles errors by configuring the HTTP error pages and the error log file (see Error Handling on page 173). Configure whether traffic history statistics are gathered (see Traffic History Statistics Gathering on page 176). Configure cookies for tracking web site users (see Configuring User Tracking on page 177). Configure detailed forensic logs for debugging purposes (see Configuring Forensic logging on page 179.). Configure SNMP provision to allow remote monitoring of Virtual Servers (see Configuring SNMP monitoring on page 182.) 9.2 Configuring Request logging A Virtual Server can log the requests that users make to it. This is useful if you want to find out who has been to your web site and what pages they have Configuring Logging and Monitoring 165

168 looked at. To specify what information should be recorded, and where, configure the logging functionality as follows: 1) Access the request logging page by clicking the Request Logging link in the configuration page menu. 2) Enable the request logging functionality by clicking the appropriate radio button. Note that request logging is switched off by default, and it is recommended that you switch it on when setting up a new system. 3) Enter the full path and name of the file in which you want the logging information to be stored. 42 To prevent users from viewing the log file, it is advisable to locate it outside the Virtual Server s document root. 4) Click the Apply changes button. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. The log file is created as soon as a user requests a file from your Virtual Server. The log file has the name you gave it with the current date appended to it. Each day a new log file is created 43 and the day s requests are recorded there. For example, if you enter /logs/myfile as the log file name, then log entries on the 30th April 2001 are saved in the file /logs/myfile Configuring the Log File Format Each time a request is made to a Virtual Server, a new entry is made in the Virtual Server s request log file. The entry can consist of various pieces of information, such as the IP address of the user who made the request, or the 166 Configuring Logging and Monitoring 42. The file path can contain %zeushome%, see The ZEUSHOME Environment Variable on page To log all requests to one file, rather than starting a new file every day, add the following line to the global.cfg file: tuning!modules!log!auto_rotate no For information about the global.cfg file, see The Global Configuration File on page By default Zeus Web Server writes the logs to the log file every 10 seconds if there are any, or writes every 32k of logs to the logfile if this is reached sooner.

169 name of the URL they requested. The log file format string controls which pieces of information are included in each log entry. By default, log file entries are in NCSA Common Log Format, which is the format most commonly understood by third-party log-analysis tools. You can change the format string to any one of a number of pre-defined formats, or create an customized string of your own. Using a customized string is useful because it gives you complete control over the content and layout of your log files. You can configure the log file format in one of the following ways: To enter a customized format string, click the appropriate radio button, then enter the string, as described in the following section. To use a pre-defined format string, click the appropriate radio button, then select a format from the drop down list. After configuring the log file format, click the Apply changes button. Using a Custom Format String The log file format string specifies which pieces of information about the requests are recorded in the log file. It can also contain additional text to make the log file entries more legible, including the carriage return character, \n. The following codes can be included in the format string: The code......records... %a The remote IP address %b The number of bytes transferred in the request (including the HTTP header). Configuring Logging and Monitoring 167

170 The code......records... %B Specifies that log entries use Binary Logging Format. This format provides a compact representation of the standard NCSA Common Log Format. Log files in this format cannot be viewed until they have been converted into Common Log Format by using the blf2clf program (see The blf2clf Program on page 379 for details). The %B code should not be used in conjunction with other codes. i %f The filename portion of the URL requested. %h The user s IP address, or host name if your Virtual Server has DNS Lookup enabled. ii %H The request protocol (e.g. HTTP, HTTPS) %l The remote logname. This is for compatibility only and will always return - %m or %M The HTTP method used for the request. %p The canonical port number of the server the request was received by. %P The PID of the process that served the request %q The query string of the request, (including the initial?), or empty if there was no query string in the request. %r The first line of the request itself, in the format: method URL protocol/version %s The HTTP status code returned by the Virtual Server. %t The date of the request, in the format: day/month/year:hh:mm:ss timezone %T The time of the request, in the format: YYMMDD-hhmmss %u The user s username, if the user had to authenticate themselves by providing a username and password to access the URL. %U The URL requested. %v The name of the Virtual Server which dealt with the request. %V The HTTP protocol and version in the format: protocol/version. 168 Configuring Logging and Monitoring

171 The code......records... %w The number of bytes of body transferred by the Virtual Server (excluding HTTP headers). %{header-line}i An HTTP header line from the request. For example, %{cookie}i records the line in the request that starts with the word cookie. %{header-line}o An HTTP header line from the output response. For example, %{Content-Type}o records the line of the response that starts with Content-Type. %{name}n The contents of a note inserted by a module. %{format}t The time, in the form given by format, which should be in strftime(3) format. \n A carriage return, which can be used to format the log file so that entries are spread over more than one line. %{gzip_bytes_in}n The number of bytes of output generated before it was compressed (see Configuring Content Compression on page 120). %{gzip_bytes_out}n The number of bytes of output generated after it was compressed (see Configuring Content Compression on page 120). %{gzip_compressi on_ratio}n The percentage ratio of the compressed output to the uncompressed output (see Configuring Content Compression on page 120). i ii Using the %B code within a custom format string is the same as selecting Binary Log Format from the list of pre-defined format strings. For more information about turning on DNS Lookup, refer to Advanced Configuration Settings on page 98. Configuring Conditional Logging You can specify that a code is only included in the format string if certain HTTP error codes have occurred. Do this by inserting the HTTP error codes as a comma-separated list between the % character and the code letter. For example, %401,403U is expanded to the requested URL only if the request returned a result code of 401 or 403. Otherwise it is entered in the log file as -. Configuring Logging and Monitoring 169

172 If you want information to be logged only if the Virtual Server does not return certain error codes, insert these HTTP codes between %! characters and the code letter. For example, the code %!200,301,302U is expanded to the requested URL if the error code is not 200, 301 or 302. Otherwise it is entered in the log file as -. Logging SSI Requests If you use SSI (Server Side Includes) 45 on your web site, then, by default, Zeus Web Server automatically logs every request for every included file. For example, if you have a standard footer which is included on every web page, then two entries are made in the log file for every page requested, one for the page itself, and one for the footer. You can eliminate these extra log entries and make the log file easier to read by turning off the logging of SSI requests, as follows: 1) In the Logging SSI Requests section, click the appropriate radio button. 2) Click the Apply changes button. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Consolidating and Splitting Multiple Request Log Files If you are running web servers on a cluster of machines, or have multiple Virtual Servers or Subservers, you may want to consolidate your request logs in one file or directory, and then post-process them in some way. There are a number of ways to consolidate the files, depending on the configuration of 45.For more information about using SSI, refer to Configuring SSI Support on page Configuring Logging and Monitoring

173 your web servers. You may want to combine one or more of the following methods to suit your specific requirements: Request Logging for a Cluster of Machines If you have a Virtual Server that is running on a cluster of machines, request logging can be configured in the following ways: By specifying a file on the local machine. In this case a separate log file is created on each machine in the cluster. By specifying a file on a shared fileserver that all the machines have access to. If the machines log to a single shared file, you may encounter problems with file corruption due to the limitations of NFS file locking. To overcome this, Zeus Web Server provides a way to automatically use a different log file name for each machine, by including one of the following codes in the log file name: The code......is replaced by... %h The name of the machine that the Virtual Server is running on. %d The domain name of the machine that the Virtual Server is running on. %v The name of the Virtual Server that served the request. For example, if you specify a log file name of /usr/local/logs/%h, each machine creates a log file called /usr/local/logs/machine-name.created-date, in the shared network directory. All the request log files are stored in this directory, from where you can re-combine and post-process them. Request Logging on Multi-Processor Machines If your machine has multiple processors, Zeus Web Server provides a way to log requests handled by each processor in a separate log file. Do this Configuring Logging and Monitoring 171

174 by using the following codes in the log file name. The codes are replaced by information about the processes running on your system, as follows: The code......is replaced by... %p The Unix Process ID of the Zeus Web Server process. (There is one process per processor.) %c Child ID number of the Zeus Web Server process. For example, if you configure the log file name for a Virtual Server to be /usr/local/logs/p_%c this results in one log file being produced per processor. Each file has a name such as /usr/local/logs/p_0.created-date, where the number corresponds to the processor that handled the requests. All the request log files are stored in the same directory, from where you can combine and post-process them. Sharing a Log File between Multiple Virtual Servers To configure multiple Virtual Servers, running on one machine, to share the same request log file, do the following: 1) Configure each Virtual Server s log file name to refer to the same file. 2) Configure each Virtual Server to produce its log file using a custom format string. The log format string should start with the %{Host}i code. For example: %{Host}i %h %l %u %t \"%r\" %s %b This enables you to distinguish between log entries for different Virtual Servers by including the name of the Virtual Server in each entry in the file. Zeus Web Server provides a script to split a combined log file into individual files for each Virtual Server. See The subserver_logsplit.pl Script on page 378 for details. Request Logging for Subservers If your Virtual Server supports Subservers, the request logging information for all Subservers is recorded in a single log file. Zeus Web Server provides a script to split the log file into individual sections for each Sub- 172 Configuring Logging and Monitoring

175 server. For further information, see The subserver_logsplit.pl Script on page Error Handling When a user requests a file that cannot be returned, Zeus Web Server records details of the request in its error log file, and returns an HTTP error page to the user. For information on customizing the appearance of these error pages, see Customizing HTTP Error Pages on page 173. For information on configuring the error log file location, see Configuring the Error Log File Location on page 176. Customizing HTTP Error Pages Zeus Web Server enables you to control which HTTP error pages are displayed when the user requests a page that cannot be returned. You may want to change these pages to give them the same look and feel as the rest of your site, or to translate them into another language. There are a number of HTTP errors which can occur, and each has its own HTTP error code and HTTP error page associated with it. If you want to change the appearance of the error page for a particular error, edit the HTML page corresponding to it. This can be done using an HTML editing program, or a text editor. i The HTML pages are named after the standard HTTP error numbers. For example, the error File not found has HTTP error number 404, and returns the page 404.html. A list of all supported HTTP error codes and their meanings can be found in HTTP Status Codes on page 323. Note: Your customized HTTP error pages are only used if the error handling functionality is enabled (it is by default). If it is disabled, Zeus Web Server returns internally generated error pages instead. Configuring Logging and Monitoring 173

176 If you have a multi-language web site and want error pages to be returned to users in an appropriate language, use the content negotiation functionality. For information on how to do this, see Language Content Negotiation of HTTP Error Pages on page 119. Specifying the HTTP Error Page Location! By default, all Virtual Servers running on a web server on a machine use a common set of HTTP error pages, which are located in the directory $ZEUSHOME/web/etc/errpages. By changing the directory that a Virtual Server looks in to find its error pages, you can give each Virtual Server its own customized set of error pages. Warning: Although it is possible to edit the files in this directory directly, you are advised to copy them to another directory, and edit them there. This is because Zeus Web Server creates a new directory during the installation (and upgrade) process, and updates all symlinks to point to this most recent directory. This means that any files in the old directory structure will no longer be pointed to and so may appear to be lost. To change the directory that a Virtual Server looks in to find its HTTP error pages, do the following: 1) Access the error handling page by clicking the Error Handling link in the configuration page menu. 2) Enter the full path of the new error page directory. 46 3) Click the Apply changes button. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page The file path can contain %zeushome%, see The ZEUSHOME Environment Variable on page Configuring Logging and Monitoring

177 Adding Dynamic Content to HTTP Error Pages HTTP error pages can contain dynamic content generated by Server Side Includes (SSI). By using SSI it is possible to configure a CGI script to run when an error occurs. This could be used, for example, to automatically the webmaster about broken links on your web site. Zeus Web Server automatically parses all error pages for SSI tags, regardless of their MIME type. There is no need to configure them to have the.shtml file extension. To run a CGI script when an error occurs, include the following line in the HTML error file: <!--#exec cgi="scriptname.cgi" --> The resulting page contains the HTML content of the original HTTP error page as well as any output produced by the CGI script. For more information about including dynamic content in HTML pages, see Configuring SSI Support on page 210. For more information on configuring Zeus Web Server to run CGI scripts, see Configuring CGI Support on page 213. Generating Error Pages in Third-Party Applications If you are using CGI scripts, PHP, or other third-party applications such as ISAPI, you can configure whether Zeus Web Server or the application generates the HTTP 404 error ( File not found ) when a non-existent file is requested. For more information see Configuring Handlers on page 139. Advanced Control of HTTP Error Pages If you want even greater control over how HTTP error pages are returned by your Virtual Server, use.htaccess files (as described in Using htaccess Files on page 199), with the ErrorDocument directive (as described in HTTP Error Page Directives on page 344). You could use this, for example, to locate individual HTTP error pages in different directories, or to configure some sections of your web site to have different error pages to others. Configuring Logging and Monitoring 175

178 Configuring the Error Log File Location i The request logs record information about each request received by the Virtual Server, as described in Configuring Request logging on page 165. The error logs record information about the rest of each Virtual Server s activity, such as when it is started and stopped, and any configuration problems encountered. Note: Error logging is always switched on and cannot be switched off. By default, all Virtual Servers record their errors in a single file, the global error log file (%ZEUSHOME%/web/log/errors). To configure a Virtual Server to log errors to another file, do the following: 1) Access the error handling page by clicking the Error Handling link in the configuration page menu. 2) In the Error Logging section, enter the full path of the new error log file. 3) Click the Apply changes button. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page Traffic History Statistics Gathering If you want to monitor the traffic on your Virtual Servers, use the traffic history pages. These enable you to view graphs of recent traffic on your system, analyzed over the last week or 24 hour period. You can only view historical traffic for Virtual Servers that have the statistics gathering functionality enabled (it is by default). Statistics gathering increases the load on a Virtual Server, and so should not be used on a performance critical web site. If you choose to disable this functionality, do the following: 1) Click the Statistics Gathering link in the configuration page menu. 2) Disable the functionality by clicking the appropriate radio button. 176 Configuring Logging and Monitoring

179 3) Click the Apply changes button. i Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Note: If you re-enable statistics gathering on a Virtual Server, you must wait five minutes before the statistics become available on the traffic history pages. For information on how to use the traffic history pages, see Using the Traffic History Pages on page Configuring User Tracking If you want to track users visits to your web site, use the user tracking functionality. This enables you to find out more about how people use your web site, such as which routes people use to navigate it, or how often they come back. i The user tracking functionality enables you to track user visits to your web site by issuing unique cookies. A cookie is a small piece of text that the Virtual Server sends to the user s browser, and that the user s browser then returns in every subsequent request. This enables the Virtual Server to track the activity of each user accurately. Note: Some users may disable cookies in their browsers, making it impossible to log information about them. Configuring User Tracking To configure User Tracking on your Virtual Server, do the following: 1) Access the user tracking page from the configuration page menu, and enable cookies. 2) Configure the cookie names, as described in the section that follows. Configuring Logging and Monitoring 177

180 3) Configure the cookie lifetime, as described in Configuring Cookie Lifetimes on page ) Optionally, configure the cookie domain, as described in Specifying Optional Cookie Domains on page 179. Specifying Cookie Names To help you track and identify cookies, each cookie generated by your web site is unique. The cookie s name can be specified by a prefix name that is combined with a random number when a request is received, to form the unique cookie name that is sent to the user s browser. It is this unique name that is returned by the user s browser with each request they make, enabling you to identify all the requests made by a certain user. You can then track, log and analyze this information. To configure the name, do the following: 1) Enter the prefix name of your cookie. It is recommended that you specify something that is likely to be unique to your web site. 2) Click the Apply changes button to update your configuration. Configuring Cookie Lifetimes There are two types of cookies: Short-lived cookies only last until the user closes their browser. They are useful for tracking a user s path through your web site. Each request made by the user is logged, and this information can be analyzed using log analysis tools. Long-lived cookies live for a specified time period. They can be used to detect that a user has returned to your site, possibly weeks later. This enables you to retain key pieces of information about your users, so that they don t have to re-enter them every time they visit your web site. Configure cookie lifetime in the following way: 1) If you want the cookie to live longer than the user s browsing session, set the radio button to Use long-lived cookies. 178 Configuring Logging and Monitoring

181 2) If you are using long-lived cookies, specify their lifetime in days and hours. Their total lifetime is the sum of these, and must be at least 1 hour. 3) Click the Apply changes button to update your configuration. Specifying Optional Cookie Domains By default each cookie that a web site generates is only returned to the web site that issued it. To share cookies (and therefore share recorded user information) between multiple web sites in the same domain, specify the cookie domain, such as mydomain.com. The cookies are then returned to all web sites in this domain. This enables you to track users, and share recorded information about them, between web sites. To configure the cookie domain, do the following: 1) Specify the shared domain. 2) Click the Apply changes button to update your configuration. Analyzing Cookie Results To collect cookie information, configure your Virtual Server to record cookie names in the request log file. To do this, use the %{cookie}i code in the request log format string. For information on how to configure request logging, see Configuring the Log File Format on page 166. Once you have configured request logging, analyze your web site s user behavior by inspecting the Virtual Server s request log file Configuring Forensic logging Forensic logging can be used to debug request processing within Zeus Web Server and to isolate faults and unexpected behaviour. 47. You can also use third party products, that use cookies to analyze page usage, such as Clickstream. Configuring Logging and Monitoring 179

182 ! Warning: Forensic logging generates a large volume of log data and reduces the performance of your web server. It also logs information that may be securitysensitive, such as cookies, usernames and passwords. This feature should be used with care on a live web site. Forensic logging occurs at two stages in the request processing cycle (see Viewing the Request Processing Summary on page 96): As soon as Zeus Web Server has read all the HTTP headers for a request, Forensic logging writes all the headers, along with a timestamp and a unique marker, to the forensic log file in $ZEUSHOME/web/log/forensic. Once Zeus Web Server has completed an HTTP request, Forensic logging writes the HTTP response headers, along with a timestamp and the same unique marker, to the forensic log file. Example log entries The following abbreviated log lines illustrate a sample transaction. [08/Jun/2004:14:39: ] +8E1EED3658E vs_name GET / HTTP/1.0 Host: User-Agent: Telnet [08/Jun/2004:14:39: ] -8E1EED3658E vs_name HTTP/ OK Content-Type: text/html Server: Zeus/4.3 Date: Tue, 08 Jun :39:08 GMT Connection: close Each line begins with a timestamp, accurate to one second, either a + or - character indicating a new or closing connection respectively and a unique ID specific to that request. Each line then contains a list of fields separated by characters: the virtual server name, first request line and request headers for a new connection log line; the virtual server name, first response line and response headers for a closing connection log line. 180 Configuring Logging and Monitoring

183 i Note: Only connections that write a response have corresponding closing connection log lines. Connections which terminate abnormally without sending any data (for example, as a result of a premature client close), do not have a closing connection log line. The forensic log information can be used in several ways: To verify that your webserver is correctly parsing input and returning the correct output. For example, you can use it to dump all input headers, such as authentication information and cookies, so you can tell exactly what request the client has sent to the server. To locate requests that typically take a long time to generate complete, by comparing the timestamps of the start and end of the request. Note that a request may be slow for a variety of reasons; the client may be on a slow connection, or a dynamic application may take a long time to generate the response. To locate requests that may have caused a webserver process to crash, for example, due to a buggy in-process ISAPI module. These requests will not have a corresponding close message, and the timestamps will match the timestamps of errors in the Zeus Web Server error log file. Analyzing the Forensic log file The logverify tool, located in $ZEUSHOME/web/bin/logverify, can be used to search for abnormal entries in the forensic log file. When you run it, it parses the forensic log file and reports any new connection lines which don t have a closing connection line, any closing connection lines without a new connection line, and any malformed lines. It can be used to quickly trim down the forensics log, removing all cleanly handled connections. Configuring Logging and Monitoring 181

184 9.7 Configuring SNMP monitoring SNMP (Simple Network Management Protocol) is an industry-standard network protocol that allows the monitoring and configuration of a network device. The Zeus Web Server can report its status, but not be configured, by SNMP. Typically, a remote computer will use SNMP to collect data from many network devices and present an overview to the user of those requiring special attention. Software that can send SNMP requests include HP s OpenView and the open source Nagios package. 48 Enabling reporting via SNMP When installing the Zeus Web Server, you will be asked if you wished to use SNMP. If you answer yes to this question, then SNMP support will be enabled. If you answer no to this question, it will not be enabled. You can change these decisions after installation with two commands. To enable SNMP, the following command will start the SNMP server, and link into the Zeus startup and shutdown sequence: $ZEUSHOME/snmp/bin/enablesnmp To disable the use of SNMP, the following command will stop the SNMP server if it is running, and remove it from the Zeus startup and shutdown sequence: $ZEUSHOME/snmp/bin/disablesmnp The SNMP server listens for requests on a port. This is specified by the agentaddress field in the file $ZEUSHOME/snmp/etc/snmpd.conf, and is chosen at installation time. The port number is reported every time the SNMP component of the Zeus Web Server is started. For example: Zeus SNMP Agent -- Master (C) Zeus Technology Ltd Portions (C) Carnegie Mellon University INFO:Listening on 1161 INFO:Zeus SNMP Agent -- Master running If necessary, you can edit the $ZEUSHOME/snmp/etc/snmpd.conf file and restart the SNMP server to change the port number Configuring Logging and Monitoring

185 You will need to import the Zeus Web Server MIB file into your SNMP software in order to monitor your Zeus Web Server by SNMP. The MIB file is located in $ZEUSHOME/snmp/mibs/ZEUS-MIB.txt Variables reported via SNMP A number of command line tools are provided with Zeus Web Server, to query variables via SNMP. To view the list of variables provided, the snmpwalk command can be used. The variable names start with the string enterprises.zeus.products.zws, and take the same variable names as those available through the monitoring system (see Real-Time Monitoring on page 73.) For example, the following command shows the state of every variable available: $ $ZEUSHOME/snmp/bin/snmpwalk -c public localhost enterprises.zeus enterprises.zeus.products.zws.zeus-4-1.zwsstat.cgi.execution.cgi-2.0 = 15 enterprises.zeus.products.zws.zeus-4-1.zwsstat.cgi.execution.fork.0 = 3 enterprises.zeus.products.zws.zeus-4-1.zwsstat.cgi.execution.nph.0 = 0 enterprises.zeus.products.zws.zeus-4-1.zwsstat.cgi.failed.context.0 = 0 enterprises.zeus.products.zws.zeus-4-1.zwsstat.cgi.failed.fork-2.0 = 0... The output of this command has been elided, since about 200 variables are reported. Descriptions of these variables can be shown by using the command $ZEUSHOME/webadmin/bin/zwsstat --list-descriptions. The hostname can be changed to query a remote host, in place of localhost shown in the example above. This allows you to query a remote server. It is possible to retrieve the value of a specific variable by using the snmpget command. For example, the following command retrieves the number of connections that have been accepted by the web server: $ $ZEUSHOME/snmp/bin/snmpget -c public localhost enterprises.zeus.products.zws.zeus-4-1.zwsstat.connections.accept.ok.0 i enterprises.zeus.products.zws.zeus-4-1.zwsstat.connections.accept.ok = 292 Note: all the Zeus variables shown are read-only. It is not possible to set them using the snmpset command, or an equivalent command. All rates are per-second. Configuring Logging and Monitoring 183

186 Setting SNMP security For security reasons, you should always set security on the Zeus SNMP server so that only authorized users can read the information. This can be done by setting the SNMP community string to a secret value that only you know. Users querying the Zeus SNMP server will have to know the secret community name to retrieve an SNMP variable. To do this, edit or add these lines in the $ZEUSHOME/snmp/etc/snmpd.conf file: rocommunity yoursecrethere rwcommunity yoursecrethere and replace the community name with your secret name. When you have done this, restart the Zeus SNMP server process, by running the following command: $ZEUSHOME/snmp/rc restart SNMP variable behaviour It should be noted that SNMP variables will wrap after 32 bits and their values will return to zero. This is most likely to occur with counter values increment rapidly, such as those which show the number of bytes served. Most SNMP viewing packages will notice the wrap around, and will are able to interpret this accordingly. The version number of Zeus Web Server is encoded into the SNMP variable name. This is because SNMP definitions are not allowed to change once released, and Zeus revises the variables available via SNMP periodically, to add new ones. SNMP variables defined by Zeus Web Server start with the string zeus-4-2, where the last two digits represent the version number. If upgrading, you may need to change the names of the variables you are monitoring to use the appropriate version number of Zeus Web Server which you have installed 184 Configuring Logging and Monitoring

187 CHAPTER 10 Configuring Access 10.1 Introduction Each Virtual Server has one or more associated web sites. By default, everyone can access all the content on each web site. Sometimes, however, it is useful to restrict access to parts of your web site. There are a number of different ways of doing this 49 : You can configure a set of access rules that control access to specified directories on either a location or user basis. Create and manage these rules using the restricting access functionality, as described in Configuring Access Rules on page 186. You can use a set of Apache-style.htaccess files to control access to different subdirectories and files. You can also use them to control support for other local functionality. Configure the Virtual Server to support.htaccess files using the htaccess functionality as described in Using htaccess Files on page 199. You can prevent one web site from using all the available bandwidth by limiting the bandwidth available to each. This protects the availability of the other web sites hosted on the machine. Do this by configuring the 49. Note that if you are using a number of different access control mechanisms, Zeus Web Server runs them in the following order: NSAPI applications, then ISAPI modules, then ZDAC authorizers, then access rules, then FastCGI applications. The request is only processed if it passes every access control mechanism. Configuring Access 185

188 bandwidth throttling functionality, as described in Configuring Bandwidth Throttling on page 202. You can prevent other web sites from 'stealing' your content and bandwidth by linking to files (such as graphics) and passing the content off as their own. Do this by configuring the referrer checking functionality, as described in Configuring Who Can Refer to Your Content on page 204. i You can also configure secure access to your web sites using SSL, as described in Configuring SSL Security for a Virtual Server on page 100. Note: It is also possible to implement your own customer authentication system using an industry standard API, such as FastCGI or ISAPI. This enables you to build customized applications that integrate fully with existing user management systems. For more information about configuring Virtual Servers to support applications using different APIs, refer to Configuring API Support on page Configuring Access Rules Background It is sometimes useful to control who can access different parts of a web site. For example, you may have some pages that you want to restrict so that only customers, or people in a particular organization, can view them. Types of Access Control There are two ways in which you can control access to web sites: You can control access for specific machines, based on IP address, host name or domain name ( host-based access control), or for specific users, based on a username/password combination ( authenticated access control). Use both approaches together for maximum security. 186 Configuring Access

189 These types of access control are described in the following sections: Host-based (machine-based) access control. This enables you to control access according to the machine that users are trying to access pages from. You can identify the machine by either IP address or host name. Users who do not have access (because they are not using an allowed machine) see an HTTP 403 Forbidden" error page instead. This can be useful if, for example, you want a simple way of restricting access to a particular organization. Note, however, that because access is controlled according to particular computers, any individual using a computer within the specified domain can view the restricted pages. This means that this type of access control is not suitable for sensitive or commercially valuable information. Note also, that the DNS system has vulnerabilities. This enables malicious users to falsify their host names, giving the impression they are in some other domain. It is therefore more secure to specify machine-based access control using IP addresses 50 (rather than host names) and to combine this with user access control. Authenticated (user-based) access control. User-based access control offers more security than computer-based access because users must supply a valid username and password before they can access the information. It is also more flexible, because it enables authorized users to connect from any machine on the network. Use both types of access control together to provide the maximum security. User-based access control requires user information to be set up and maintained, and so is more complicated to administer than computerbased access control. When a user tries to access a file that uses user-based access control they see an HTTP 401 ( Unauthorized ) error page, with a dialog box requesting a username and password. Zeus Web Server checks this against its user information and only returns the file if both fields are correct. Otherwise 50. Although even the source address of TCP/IP connections can sometimes be spoofed. Configuring Access 187

190 it returns the 401 Unauthorized error page again, enabling the user to try again. Once a user has been authenticated successfully, the authentication information supplied in the dialog box is then included (as an Authorised HTTP header) with all subsequent requests (so that the user does not have to re-enter this information for every resource requested). Note that the browser sends username and password information unencrypted 51, and so it is vulnerable to being intercepted. Although this is also true for other Internet protocols such as telnet and FTP, the frequency of HTTP requests increases the risk. Introducing Access Rules The restricting access functionality enables you to control access to the Virtual Server s web site 52. You control access by building up a set of access rules. Each rule either allows or denies access to specified users and directories. The following sections describe how to configure this functionality and build up a set of rules. How Zeus Web Server Applies Access Rules Access to the document root subdirectory hierarchy is configured by applying a set of access rules. Each rule specifies: Whether to allow or deny access to the specified resource. Which directory to apply the rule to. Note that a rule for a particular directory also applies to all its subdirectories. Whom to apply the rule to. This can be specified by location (IP address or host name), by user (username and password), or by both. The Virtual Server applies the rules to each request in the order in which they are listed. It checks each rule to see if it applies to the requested URL and 51. Unless the Virtual Server is configured to use SSL, as described in Configuring SSL Security for a Virtual Server on page Access rules can be applied to Subserver enabled Virtual Servers in the usual way. 188 Configuring Access

191 HTTP method. If it does, the Virtual Server checks whether the rule applies to the user, in the following way: a) If a host name or domain name is specified then it is evaluated using reverse DNS lookup 53, and compared with the user s computer. b) If an IP address is specified then it is compared with the user s computer. c) If a user is specified then the username and password are requested and compared. If all the fields of a rule match then the Virtual Server returns the resource if the rule is an allow rule and denies the request if the rule is a deny rule. If the rule does not match, then the Virtual Server moves on to the next rule. If all the rules fail to match then the Virtual Server returns the requested file. This means that you should order the rules so that the most specific rules are listed first. For example, if you want to only allow certain users access to a directory, create two rules as follows: The first rule should be an allow rule, specifying the names of the users to allow. The second rule should be a deny rule, denying access to all users. There is no limit to the number of rules you can add, although a large number may become difficult to manage, and may slow down request response times. In this case you should consider subdividing your web site into multiple Virtual Servers, or using.htaccess files to control access, as described in Using htaccess Files on page 199. Configuring the Access Rules: Overview To configure the access rules, do the following: 1) Decide whether you are going to use computer-based access control, user-based access control, or a combination of both. These are described in Types of Access Control on page which must be enabled on this Virtual Server, as described on page 99. Configuring Access 189

192 2) If you are using user-based access control, decide how you will store your user and password details, as described in Specifying the User Database on page 190. If you decide to store user details in an internal database, then configure a set of users, as described in Configuring Access Users in the Internal Database on page 191. If you are using LDAP, then configure this as described in Using an LDAP Database on page ) Enable the restricting access functionality. 4) Configure new rules, as described in Configuring Access Rules on page ) Re-order them appropriately, as described in Re-ordering Rules on page ) Modify existing rules, if required, as described in Modifying Rules on page 198. Specifying the User Database If you are using user-based access control you need to configure access users and their associated passwords. You can additionally configure access groups, which are a way of collecting users together for ease of management. 190 Configuring Access

193 Configure the users and groups in one of the following ways: Set up user information in an Internal database in the Virtual Server. For information on how to do this, see Configuring Access Users in the Internal Database on page 191, and Configuring Access Groups in the Internal Database on page 192. Access user information from an external LDAP database. For information on configuring this, see Using an LDAP Database on page 192. Access user information directly from existing operating system account information. For information on configuring this, see Using an Operating System Lookup on page 194. Configuring Access Users in the Internal Database Configure access users by clicking the Users and Groups link in the configuration page menu. This takes you to the Access Users and Access Groups page. In the Configuring Access Users and Access Groups section, ensure that users and groups are configured to be stored in an internal database. If not, select this option and then click the Apply changes button. The page displays the currently configured access users and groups. To add a user, do the following: 1) In the Adding an Access User section, enter the user s username. This is case sensitive. 2) Enter the user s password. 3) Re-enter the password to confirm it. 4) Click the Apply changes button. The new user is added to the list of configured users. This list is displayed in alphabetical order. To delete a user, click their Delete check box, then click the Apply changes button. Configuring Access 191

194 To change a user s password, access the Changing a User s Password page by clicking the username link. Enter the new password twice, then click the Apply changes button. Configuring Access Groups in the Internal Database You can use access groups to simplify your user management. You can group a number of users together and then specify the group in the access rule, rather than the entire list of users. Configure access groups by clicking the Users and Groups link in the configuration page menu. In the Configuring Access Users and Access Groups section, ensure that users and groups are configured to be stored in an internal database. If not, select this option and then click the Apply changes button. The page displays the currently configured access users and groups. To add an access group, do the following: 1) In the Adding an Access Group section, enter the access group name. Group names are case sensitive, and can only contain letters, numbers and underscore characters. 2) Select which users to include in the group. 3) Click the Apply changes button. The new access group is added to the list of configured groups, which is displayed in alphabetical order. To delete an access group, click the Delete check box next to it, then click the Apply changes button. To change which users are in a group, click the group name link to access the Changing the Members of an Access Group page. Select or de-select members of the group, then click the Apply changes button. Using an LDAP Database An LDAP server is an external server that uses the Lightweight Directory Access Protocol to provide directory services. If you have a large number of 192 Configuring Access

195 users whose details are already stored using an LDAP server, then you can use this to provide your user access information. You should only use this option if you are familiar with LDAP. To configure the access rules to use user information from your LDAP server, do the following: 1) On the Access Users and Access Groups page, configure users and groups to be stored in an external LDAP server, then click the Apply changes button. This changes the page to display the LDAP configuration section. 2) Enter the LDAP authentication details. If your LDAP server requires its clients to be authenticated, you must tell Zeus Web Server how to authenticate itself when it contacts the LDAP server. LDAP authentication is composed of two parts, a Binddn and a Password, which can be obtained from your LDAP server administrator. Enter these in the fields in the LDAP Authentication section. 3) Set the LDAP URL to query a user s password. Specify the LDAP URL that Zeus Web Server uses to query the LDAP server for the user s password. When entering the LDAP URL, replace the actual username with $u. This symbol is converted into the appropriate username when the query is sent to the LDAP server. For example, the following LDAP URL queries the LDAP server located at ldap.myserver.com, and asks for the pword attribute of the required user: ldap://ldap.myserver.com/o=zeus?pword?sub?cn=$u The section cn=$u is replaced by cn=username when the query is sent to the LDAP server. 4) Set the LDAP URL to query which groups a user is in. Specify the LDAP URL that Zeus Web Server uses to query the LDAP server for the user s group(s). This URL is in the form of a query that passes a username to the LDAP server and requests the corresponding group(s). When entering the LDAP URL, replace the actual username with $u. 5) Set the Cache Timeout value. The Virtual Server uses a cache to improve query times and reduce the load on the LDAP server. Each time the Virtual Server queries the LDAP Configuring Access 193

196 server it stores the results in the cache. If it needs to perform the query again later, while the previous results are still in the cache, it can simply use the results from before, rather than performing the query again. Results are held in the cache for a specified time period, specified in the Cache Timeout field, which is measured in seconds. 6) Click the Apply changes button. Using an Operating System Lookup You can configure the Virtual Server to access user information directly from existing OS account information using the operating system lookup. This is useful if you are controlling access to a set of people who already have accounts set up on your web server machines, such as for an intranet. It means that you can use the existing operating system account information directly. To configure the access rules to use your operating system user information, do the following: 1) On the Access Users and Access Groups page, configure users and groups to be are retrieved from an operating system lookup, then click the Apply changes button. This changes the page to display the Operating System Lookup configuration section. 2) Set the Cache Timeout value. The Virtual Server uses a cache to improve query times and reduce the load on the OS Lookup system. Each time the Virtual Server does a lookup, it stores the results in the cache. If it needs to perform the same lookup again later, while the previous results are still in the cache, it can simply use the stored results, rather than performing another lookup. Results are held in the cache for a specified time period, specified in the Cache Timeout field, which is measured in seconds. 3) Click the Apply changes button. i Note: If your operating system is using shadow passwords, the web server will not be able to read the stored password. You should only use this lookup if the 194 Configuring Access

197 password is readable by the user the web server is running as (for example, when using NIS, LDAP or a regular /etc/passwd file with passwords in). Configuring Access Rules Once you have configured a set of users (if you are using user-based access control), the next step is to configure the set of access rules. By default, the Virtual Server has no access rules configured, and so anyone can access all of its web site. To configure access rules, click the Restricting Access link from the configuration page menu, and enable the functionality by clicking the appropriate radio button. The restricting access page shows a list of the currently configured access rules. To add a rule, do the following: 1) Click the Add a Rule button. This adds an empty rule to the bottom of the list of rules, and enables you to edit it. 2) Select whether this rule allows or denies access to a section of your web site. 3) Select which of the HTTP methods (GET, POST and PUT) the rule acts on. The GET method is used when users request web pages. POST is used to send data to certain CGI scripts. PUT is used when users upload files to the Virtual Server. 4) Enter the directory path under the Virtual Server s document root that the rule applies to. The rule applies to this directory and all subdirectories of it. Normally this is a simple directory path, starting with a / character. It is also possible to use a regular expression, in which case the rule applies to any directory path that matches it. To use a regular expression, enter it prefixed with a ~ character. For more information about regular expressions, see Using Regular Expressions on page ) If you want to use machine based access control, specify the host names or IP addresses of the machines that the rule applies to. For information on how to do this, see Specifying Host Names and IP Addresses on page 196. Configuring Access 195

198 6) If you want to use user-based access control, you can do this in the following ways: You can make the rule apply to all users by selecting Any valid user. You can make the rule apply to one or more users by selecting Only these users, and then specifying each of the users. Do this in one of the following ways, depending on how users and groups are configured: If they are stored in an internal database, the users are listed in the Users selection box. Highlight the users that you want the rule to apply to. If they are stored in an external database, you must enter each one manually. To do this, enter the name of a user into the Add User field, then click the Apply changes button. Repeat this for each user you want to add. You can restrict access to all the users in one or more of the access groups that you have configured. Do this in one of the following ways, depending on how users and groups are configured: If they are stored in an internal database, the groups are listed in the Groups selection box. Highlight the groups that you want the rule to apply to. If they are stored in an external database, you must enter each one manually. To do this, enter the name of a group into the Add Group field, then click the Apply changes button. Repeat this for each group you want to add. To configure a rule which applies to a combination of users and groups, specify them both. 7) If you are using user-based access control, you can enter an Authentication Realm String. This is the text that appears in the authorization dialog box that users must complete. 8) Once you have finished entering the rule, click the Save button. Specifying Host Names and IP Addresses Domain names are usually allocated by organization and so provide an easy way of identifying users from those organizations. Note that if you want to 196 Configuring Access

199 set up access control using host names, then the Virtual Server must be configured with DNS lookup (see Advanced Configuration Settings on page 98). IP addresses, on the other hand, are usually allocated as blocks or subnets as required, and so one organization can have a number of IP subnet blocks. They should be listed, as is Internet convention, by converting each of the four bytes to a decimal representation, and separating each byte with a.. You can specify IP subnets in one of the following ways: 1) Specify a partial IP-address by specifying the start of the IP address with a trailing.. For example, specify 10. to indicate the class A network. 2) Specify a network/netmask pair, in the form A.B.C.D/X.Y.W.Z where A.B.C.D is a network, and X.Y.W.Z is a netmask, such as / You can also specify both IP addresses and host names using extended regular expressions. In this case, prefix it with a ~ character. This enables you to use sophisticated pattern matching but must be used carefully to avoid security holes. For more information about using regular expressions, refer to Using Regular Expressions on page 389. Examples Absolute Names Sub Domains ribble.zeus.co.uk swale.zeus.co.uk.zeus.co.uk.co.uk Absolute IP Numbers IP Subnets You can also enter a network/n CIDR specification such as A.B.C.D/n where A.B.C.D is a network, and n is a number between 1 and 32 specifying the number of high-order 1 bits in the netmask. For example, /8 is the same as / Configuring Access 197

200 IP network/netmask pair / / IP network/cidr representation /24 Any host at zeus.com Modifying Rules Once you have saved a rule, it is displayed in the list of rules in summarized format. To modify any of the parts of the rule, click the rule s Edit button. This expands the rule so that you can modify any part of it. After changing the rule, click its Save button. To delete a rule, click its Delete check box, then click the Apply changes button. To disable a rule without deleting it, change its status to Disabled and click the Apply changes button. The rule is no longer used, but its configuration remains intact. The rule can be re-enabled later. Re-ordering Rules When an access-controlled resource is requested, the Virtual Server evaluates and applies the rules in order. You can re-order the list by moving rules up or down. To move a rule up or down the rule list, click the appropriate arrow icon in the re-order column. This moves the rule up or down one place in the list. Debugging Rules /16 ~.+\.zeus\.com$ It can become difficult to analyze and debug the behavior of a large number of complicated access rules. When this happens, it can be helpful to enable extra logging information in order to record and see which users are being allowed or denied access to the web site. 198 Configuring Access

201 Configure this by clicking the appropriate radio button in the Access Diagnostics section. The Virtual Server then logs extra information about each request to the error log file, showing how the access rules are applied. i Note: This option generates a lot of additional logging information and should only be used temporarily while developing new access rules. It should not be used on live web sites. For more information about the error log file, refer to Configuring the Error Log File Location on page Using htaccess Files Background It is sometimes helpful to be able to configure how requests to individual directories are handled and to delegate this control to those responsible for the local content. For example, you might want to password protect some subdirectories, or prevent directory listings in another. This section describes how to configure different areas of a web site using.htaccess files. Introducing.htaccess Files The.htaccess functionality enables you to configure the Virtual Server dynamically, and allows delegated configuration.htaccess files enable you to specify local configuration rules (directives) throughout the document root directory tree, and delegate this control to those who control the local content. By default, these files are named.htaccess, and so are commonly referred to as htaccess files. Note, however, that their file name is configurable. They are simply text files that contain configuration directives that apply to the files in the local directory and its subdirectories. Configuring Access 199

202 There are two types of.htaccess files: The global.htaccess file can specify the settings for any file, directory or URL in the Virtual Server s web site. Its directives are applied to all requests, although they can then be overridden by the local.htaccess files. It is held outside the document root. Local.htaccess files can be placed in any directory within the document root. Their settings override the global settings and any settings in files further up the hierarchy. This enables you to configure the behavior of the Virtual Server for segments of the document tree by editing a single file. Some directives can only be used in the global.htaccess file - see Supported Directives on page 327. Enabling and Configuring htaccess File Functionality Configure htaccess file functionality by clicking the htaccess Support link in the configuration page menu. Enable the Virtual Server s htaccess file support by clicking the appropriate radio button. You can then configure the htaccess file functionality in the following way: 1) Specify the full path and file name of your global htaccess file. Note that because this controls the security of your web site, this should be located outside the Virtual Server s document root. 2) Specify the file name for your local.htaccess files (described in the previous section). This is the file name that the Virtual Server will look for in every subdirectory of its document root 55. 3) Enable automatic headers and footers, if required, as described in Enabling Automatic Headers and Footers on page 201. Supported htaccess Directives For detailed information about the.htaccess file format, how the Virtual Server applies their settings and for a list of supported directives with infor- 55.Unless configured otherwise, as described in The AllowOverride Directive on page Configuring Access

203 mation about each and their parameters, refer to Using htaccess Directives on page 325. Enabling Automatic Headers and Footers This section enables you to configure a Virtual Server to attach header or footer sections to all its web pages automatically. This enables you to give a standard look to your web site, for example, by adding a navigation bar to the top of each page. Enable this functionality by clicking the appropriate radio button. Note that you should disable this functionality to optimize processing speed on performance critical sites.! The header and footer sections are fragments of HTML pages that you create and store in individual files. You specify which pages on your web site have a header or a footer appended to them by setting up htaccess directives. When a user requests a file that has a matching htaccess directive, the user receives the file with the required header joined to the beginning, or footer joined to the end. Warning: The header and footer sections are simply concatenated to the original HTML files, without any additional processing taking place. Therefore you must structure your web pages, header and footer sections in such a way that valid HTML files are produced. Adding Common Headers to Web Pages To configure headers, use the PageHeader directive in the.htaccess file. Syntax: PageHeader file Parameters: file The full path and file name of the header file, relative to the Virtual Server s document root. For example, to append the /docs/header.html file onto the start of all files that have a.html extension, use the following directive: Configuring Access 201

204 <Files *.html> PageHeader /docs/header.html </Files> For more information about the.htaccess file format refer to Using htaccess Directives on page 325. Adding Common Footers to Web Pages To configure footers, use the PageFooter directive in the.htaccess file. Syntax: PageFooter file Parameters: file The full path and file name of the footer file, relative to the Virtual Server s document root. For example, to concatenate the /docs/footer.html file on to the end of all files in the /sales directory, use the following directive: <directory /sales> PageFooter /docs/footer.html </directory> For more information about the.htaccess file format refer to Using htaccess Directives on page Configuring Bandwidth Throttling Bandwidth throttling enables you to limit the bandwidth available to any given web site. It can be used to ensure that no single web site uses all the available bandwidth, compromising the availability of other web sites hosted by the same web server. 202 Configuring Access

205 You can limit a web site s bandwidth in the following ways: You can specify a maximum number of bytes per second that the Virtual Server can deliver to users. Zeus Web Server slows down requests if necessary, keeping the average delivery rate below this limit. For example, you may have an Internet connection with a total bandwidth of 200,000 bytes/second, and want to throttle one of your Virtual Servers so that it can never use more than 10% of the bandwidth. To do this, set the maximum transfer rate of the Virtual Server to 20,000 bytes/second 56. You can specify a maximum number of simultaneous requests that can be made to the Virtual Server. If the maximum is exceeded, the extra requests receive the HTTP error code 503 ( Service Unavailable ). Setting a Throttling Limit To set a throttling limit, do the following: 1) Access the bandwidth throttling page by clicking the Bandwidth Throttling link in the configuration page menu. 2) Enable the bandwidth throttling functionality by clicking the appropriate radio button. 3) If you want to limit the maximum bandwidth that a web site can use, enter a value (in bytes per second) in the Configuring the Maximum Bandwidth section. If you do not want to limit the transfer rate, enter 0. If you set a limit on bandwidth you may not notice the limit immediately taking effect. This is because it is enforced as an average over a period of time. 4) If you want to limit the number of simultaneous requests that can be made to the server, enter a value in the Configuring the Maximum Num- 56. Note that a cable modem provides approximately 16,000 bytes/second, a 256k leased line provides approximately 32,000 bytes/second, and a T1 connection provides approximately 180,000 bytes/second. Configuring Access 203

206 ber of Simultaneous Requests section. If you do not want to impose a limit on connections, enter 0. The maximum number of simultaneous requests is not the same as the maximum number of simultaneous users, as a user s browser may well make more than one request at the same time (usually up to two). 5) If your Virtual Server has Subservers, then by default, the throttling limits that you specify are applied to all the Subservers combined. That is, if you set a limit of 32,000 bytes per second for a Virtual Server, then the total traffic on all its Subservers combined cannot exceed this figure. To configure whether throttling limits are applied to the Virtual Server as a whole, or to each Subserver individually, click the appropriate radio button. 6) Click the Apply changes button. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page Configuring Who Can Refer to Your Content You can prevent other web sites from stealing your bandwidth by using the referrer checking functionality. A web site may attempt to steal your bandwidth by making links to files (such as images) on your web site, rather than storing the files on their own web server. A visitor to such a web site views HTML pages from that web server, but receives the images within those pages from your web site. This results in unwanted traffic on your web server, and means that your files are used without your permission. Zeus Web Server can stop other web sites from stealing your bandwidth by detecting which HTML page a user s browser is displaying when it requests a file on your web site. If the browser is displaying a web page from another web server when it requests one of your files, the request can be denied. A Virtual Server can be configured to automatically check requests to see if this is happening. This checking places an extra load on the server, so the Virtual Server should be configured to only check requests for the types of 204 Configuring Access

207 files that are commonly stolen. This is done by specifying the MIME types for which requests should be checked. When your Virtual Server detects that another web site has attempted to steal your bandwidth, a message is logged to the Virtual Server s error log file. This message includes the URL of the page which caused the denial, to help you identify the web site that is stealing your bandwidth. Configuring Referrer Checking To configure a Virtual Server to detect and prevent bandwidth stealing, you specify which MIME types should be checked. Do this in the following way: 1) Access the referrer checking page by clicking the Referrer Checking link in the configuration page menu. 2) Enable the referrer checking functionality by clicking the appropriate radio button. 3) In the Files to Check section, specify the MIME types for which requests should be checked, in either of the following ways: Enter a comma separated list of MIME types, then click the Apply changes button. Add MIME types to the list one at a time, by selecting them from the drop down list and clicking the Apply changes button. You may add as many MIME types as required.! Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Warning: If you add the MIME type of standard web pages (normally text/html ) to the list of files to check, other web sites will not be able to link to any standard web page on your web site. Redirecting Denied Requests When a user requests a web page from a web site that is attempting to steal your bandwidth, the user receives the page without the embedded files Configuring Access 205

208 because Zeus Web Server denies the requests. If the files were images, the browser displays them as if they were broken links. If you want to configure Zeus Web Server so that an alternative file is returned instead, do the following: 1) In the Redirecting Denied Requests section, enter the URL of the file to return. 2) Click the Apply changes Button.! Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Warning: If you configure a denied request to be redirected to a file of a different type, the user s browser will not be able to display it. For example, if the request was for an image file, and is redirected to an HTML file, the user s browser cannot display it. Allowing Specified Web Sites to Use Your Bandwidth To allow specified web sites (such as other web sites you own) to link to your web site content without being tested for bandwidth stealing, do the following: 1) Enter a comma separated list of web sites that can link to your content. Web Sites can be specified by their host names, IP addresses or IP masks. 2) Click the Apply changes button. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Denying Requests with no Referrer Header Zeus Web Server uses the referrer header 57 of the user s request in order to determine what page the user s browser was displaying when it requested a file. However, if a user requests a file by typing its URL directly into their 57.The name of this header is incorrectly spelled in the HTTP/1.0 specification as referer. 206 Configuring Access

209 i browser, Zeus Web Server does not receive a referrer header with the request. By default, a Virtual Server permits requests that do not have a referrer header, and does not treat them as requests to steal your content. If you want to prevent users from viewing files directly in this way, configure Zeus Web Server to deny requests for files when there is no referrer header by clicking the appropriate radio button. Note: Bear in mind that some browser plug-ins, such as audio players, may not send referrer headers with requests for files. Configuring Access 207

210 208 Configuring Access

211 CHAPTER 11 Configuring API Support 11.1 Introduction Zeus Web Server supports a number of APIs that enable you to extend and enhance your web sites by developing and integrating external applications with it. They enable the Virtual Server to pass requests to different applications, which can be located either locally or remotely, to authenticate requests or to process requests, and generate content before sending it back to the client. This can enable you to produce dynamic web sites, customized for individual visitors. For an introduction to static and dynamic content, refer to Web Server Functionality on page 28.! In addition, by running external applications using these different interfaces you can move the burden of dynamic content generation to another machine, shared between a number of Virtual Servers. This can significantly increase the performance of your Zeus Web Server machines, by off-loading some of the processing overhead onto a separate machine, and enabling them to deliver pages more quickly. This can increase the performance and fault tolerance of your web sites. Warning: Running external applications on your web server system may compromise your system security. Applications have access to machine resources and parts of the file system. It is important to ensure that you understand the security implications of the applications that you are running, and configure each Virtual Server appropriately. Configuring API Support 209

212 This chapter introduces each API and describes how to configure a Virtual Server to support applications written using them. API Described in section... SSI Configuring SSI Support on page 210 CGI Configuring CGI Support on page 213 FastCGI Configuring Support for FastCGI on page 224 ISAPI Configuring ISAPI Support on page 236 Java Servlets Configuring Java Servlet Support on page 242 NSAPI Configuring NSAPI Support on page 245 Perl Using Zeus Perl Extensions on page 295 ZDAC Configuring Support for the ZDAC API on page 248 For more background information about each API, its strengths and weaknesses, and typical usage, refer to the API Examples and Documentation section at: Configuring SSI Support Introducing SSI SSIs (Server-Side Includes) are tags that are embedded in HTML pages. They are the simplest way to generate dynamic content but are not very powerful, and are generally only used for embedding simple text or files in pages. They are particularly suitable for formatting documents by including standard document elements (such as headers and footers). Zeus Web Server parses these tags and generates the content appropriately before returning the page to the user. Unlike other web servers, Zeus Web Server recursively parses SSI content included in, or generated by, SSI tags, enabling you to embed SSI directives in included files. Configure support for SSI by clicking the SSI link in the configuration page menu. 210 Configuring API Support

213 Using SSI Directives SSI directives are made up of a command and its parameters and arguments, in the following form: <!--#command parameter(s)="argument"--> For a list of the SSI directives that Zeus Web Server supports, and more information on each, with examples, refer to the API Examples and Documentation section at: This example shows the SSI echo directive embedded within some simple HTML: <html> <head><title>ssi Variables</title></head> <body><h1>ssi Environment Variables</h1> <pre>request_method: <!--#echo var="request_method"--></pre> </body> </html> Zeus Web Server parses this to produce: <html> <head><title>ssi Variables</title></head> <body><h1>ssi Environment Variables</h1> <pre>request_method: GET</pre> </body> </html> Configuring SSI Support Zeus Web Server parses any files configured with a MIME type of text/x-server-parsed-html for SSI directives. This MIME type is mapped to the.shtml file extension by default. Use this to configure Zeus Web Server to parse any given file type for SSI tags, such as a static file, CGI script or Java Servlet. For more information about configuring other file extensions with this MIME type, refer to Adding a MIME Type on page 106. Configuring API Support 211

214 i Note: The SSI exec command enables you to run programs on the Virtual Server. Because running programs has additional security implications, you must enable support for the exec command explicitly. This is described in Restricting CGI Script Locations on page 215. If you set this, then you must also ensure that you enable CGI support, as described on page 215. Configuring SSI Handlers The SSI Handlers section enables you to define custom SSI tags. By adding new SSI tags and modifying existing ones you can create a sophisticated custom authoring environment: You can configure the tags to be mapped onto any type of request - such as a request for a CGI script, a FastCGI program, or ISAPI application. For example, you could configure an SSI tag my_isapi_handler to be mapped onto /isapi-bin/handler.dll. In this case the SSI tag <!--#my_isapi_handler--> is mapped to <!--#include virtual="/isapi-bin/handler.dll"-->. Any additional parameters to the SSI tag are encoded as a QUERY_STRING that is passed to the handler. For example: <!--#my_isapi_handler color="dark blue"--> is mapped to <!--#include virtual="/isapi-bin/handler.dll?color=dark+blue"-->. You can re-map existing tags (except for #include). This could be used to disable access to particular tags. For example, you may wish to let your users author pages which use simple SSI tags, but stop them using the exec tag which can be regarded as more powerful and harder to secure. Alternatively, you could remap the exec tag onto a handler which examines the parameters and only executes permitted programs. Configure SSI handlers in the following way: 1) Specify the SSI tag that is to be mapped, in the SSI Tag field. 2) Specify the handler that it is to be mapped to, in the Handler field. 212 Configuring API Support

215 3) Click the Apply changes button. Zeus Web Server adds the tag and its handler to the list of SSI handlers. You can then do the following: Modify its value by simply editing it and clicking the Apply changes button. Remove it by setting the Delete check box and clicking the Apply changes button. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page Configuring CGI Support Introducing CGI Zeus Web Server supports the Common Gateway Interface. This interface is used to run an external program - a CGI script - as a result of a client request and return its output (usually an HTML page) to the client. The Virtual Server passes the request to the CGI script, which only runs for the duration of the request. CGI scripts can be written in almost any language, and are extremely powerful because they have very few limitations. They are often written in C or Perl, and so there are many libraries freely available in these languages to help process request data. Those writing CGI scripts must be aware of the security implications of running a program on a web server. You can however configure extra security by tightly controlling the environment and directories in which the scripts can be run. CGI scripts are flexible, easy to develop and easy to deploy, but can significantly impact web site performance and scalability because a new process is forked to handle each request for a CGI script. They are therefore most appropriate for lightly-loaded web sites and for prototyping web applications in a development environment. Configuring API Support 213

216 Configure support for CGI scripts by clicking the CGI - General link in the configuration page menu. Simple Example The following example illustrates a simple CGI script written in Perl: #!/usr/bin/perl print "Content-Type: text/html", "\n\n"; print "<HEAD><TITLE>Environment example</title></head>", "\n"; print "<BODY><H1>Some Environment Variables</H1>", "\n"; print "The server host name is : ", $ENV{'SERVER_NAME'},"<p>"; print "and the client is : ", $ENV{'HTTP_USER_AGENT'},"<p>"; print "<HR>","\n"; print "</BODY></HTML>"; exit 0 The first line specifies the location of the Perl interpreter. The second line tells the client that the script is returning HTML output. The rest of the script prints out the HTML page and displays the values of some environment variables along with a brief description of them. The last line simply ends the Perl script. For more information about CGI and for some sample scripts, refer to the API Examples and Documentation section at Setting up a CGI Script Directory This section describes how to set up a directory in which to run CGI scripts. 1) Create a directory, such as /my_home/cgi-bin/. It is recommended that you create this directory outside the document root for greater security (see Restricting CGI Script Locations on page 215). 2) Configure this directory to hold CGI scripts and appear to be within the document root, as described in Configuring Aliases for CGI Script Directories on page 216. For example, create an alias of /cgi-bin/ for the actual directory /my_home/cgi-bin/. The Virtual Server then automatically passes all requests for items in /cgi-bin/ to /my_home/cgi-bin/, and runs them as CGI scripts. 214 Configuring API Support

217 3) For extra security you can configure the Virtual Server to run CGI scripts in this directory only, as described in Restricting CGI Script Locations on page 215. You can now place scripts, such as my_script, in /my_home/cgi-bin/. Users access and run it by entering the URL Enabling and Configuring General CGI Support Enable the Virtual Server s CGI support by clicking the appropriate radio button 58. You can then configure the CGI environment by setting: The locations in which CGI scripts can be run, as described on page 215. Aliases for CGI script directories, as described on page 216. Additional CGI environment variables, as described on page 217. CGI error logging options, as described on page 218. i Note: You must ensure that all your CGI script files have their executable flags set. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. You can configure additional security settings by clicking the CGI- sandbox link in the configuration page menu, and using the Sandboxing CGI Scripts page, as described in Configuring Additional CGI Settings on page 219. Restricting CGI Script Locations You can choose whether to enable CGI scripts to run in any directory, or whether to confine them to specified directories. If they can be run from any 58. This also provides support for nph-cgi scripts. To use these, configure CGI functionality in the usual way, and ensure that your nph-cgi script names start with nph-. The nph-cgi script is then responsible for generating the byte stream that is returned directly to the client without any web server post-processing. Configuring API Support 215

218 directory then CGI scripts are identified using the application/x-httpdcgi MIME type. Restricting CGI scripts to specified directories provides additional security as you can then control access to these directories more tightly, and so can control who can write and modify the scripts. This is often used in conjunction with CGI aliases (as described in Configuring Aliases for CGI Script Directories on page 216) to enable scripts to run in a directory that is outside the document root, thus providing even greater security. This is because you can then prevent users with write access to the document root from being able to write to the CGI script directory. 1) Configure whether CGI scripts are restricted or not by clicking the appropriate radio button. If you specify that CGI scripts can run anywhere, you can then also configure the Virtual Server to support the SSI exec command. Refer to Configuring SSI Support on page 210, for more information about SSI. Click the Enable SSI exec radio button to enable you to call CGI programs by embedding an exec command within an SSI file. If you restrict CGI scripts to CGI alias directories (created as described below), you cannot configure the Virtual Server to support the SSI exec command. 2) Click the Apply changes button to update your configuration. Configuring Aliases for CGI Script Directories Use CGI aliases to make your CGI script directories appear to be in the document root. For more information about aliases, refer to Configuring URL Mapping on page 126. Configure CGI aliases in the following way: 1) Specify the location where you want the directory to appear under the document root in the Map requests for field. This is the location that users will specify in a URL. An alias to a directory must end with a /. 216 Configuring API Support

219 2) Specify the actual location of the directory in the Map requests to field. This can be expressed in either of the following ways: As an absolute path, for example, /sales/pricelist/ As a path relative to the Zeus Web Server installation directory using %zeushome% to represent the installation directory. 3) Click the Apply changes button to update your configuration. Zeus Web Server adds the CGI alias to the list. You can then do the following: Modify its value by simply editing the value and clicking the Apply changes button. Remove it by setting the Delete check box and clicking the Apply changes button. Configuring Additional CGI Environment Variables The CGI interface passes information to the CGI script using environment variables 59. The script accesses these in the same way as any other environment variable. Zeus Web Server supports all the standard CGI/1.1 environment variables 60, which provide access to information such as the location of the client and its browser type. To pass additional parameters to a CGI script you can set up new environment variables that are specific to the CGI scripts on this Virtual Server. Do this in the following way: 1) Enter a name for the new environment variable in the Name field. 2) Enter its value in the Value field. 3) Click the Apply changes button to update your configuration. 59. In particular, PATH_INFO is set to the part of the URL following the alias and PATH_TRANSLATED is set to docroot/path_info. So, for example, if an alias of /myprogram is set up for /usr/local/myprogram.cgi then a request for is passed to /usr/local/myprogram.cgi. PATH_INFO is set to /sales/us.html and PATH_TRANSLATED is set to docroot/sales/us.html. 60. See ncsa.uiuc.edu/cgi/env.html Configuring API Support 217

220 i Zeus Web Server adds the environment variable to the list of configured environment variables. You can then do the following: Modify its value by simply editing the value and clicking the Apply changes button. Remove it by setting the Delete check box and clicking the Apply changes button. Note: Other APIs, such as local and remote FastCGI can also read the CGI Environment Variables using the standard API interface to read the environment. Configuring CGI Error Logging By default, CGI script errors (output to stderr) are logged in the Virtual Server error log. You can, however, configure them to be logged separately in an individual CGI error log file. This can be particularly useful if you are running a Virtual Server that supports Subservers, because each Subserver s CGI errors can be logged in an individual CGI error log file. This helps determine which Subserver the errors came from and enables you to delegate ownership of these files. 1) Configure separate logging of CGI errors by setting the appropriate radio box. 2) Specify the full path to the CGI error log file in the Log file name field. Note that you can build up the path and file name using the parameters listed in the table below this field. For example, if you specify a log file name of %r/../logs/cgi-errors.%t, for a web site with a document root of home/website/main/docroot, then the Virtual Server logs CGI errors in /home/website/main/logs/cgi-errors.todays_date. 3) Specify the maximum size of this file in kb (or enter 0 - zero- to specify no limit). Once the error log reaches this size, it is emptied. 218 Configuring API Support

221 4) Specify the owner of the CGI error log file. You can specify either the document root owner or the user that the CGI script runs as (configured in step in Configuring CGI Sandboxing on page 219). 5) Click the Apply changes button to update your configuration. Configuring Additional CGI Settings Once you have set up basic CGI support, as described in Enabling and Configuring General CGI Support on page 215, you can configure the following: CGI ulimit configurables, as described on page 220. How many scripts can run concurrently, as described on page 221. CGI security configurables, as described on page 221. CGI script chroot jails, as described on page 223. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Configuring CGI Sandboxing A CGI sandbox is a way of restricting and containing the CGI script operating environment to reduce security risks. Configure support for CGI sandboxes by clicking the CGI - Sandboxing link in the configuration page menu. When the Virtual Server receives a request for a CGI script it forks a child process to run the CGI script, and sets the sandbox parameters. The script reads the input passed to it, runs, passes back its output to Zeus Web Server and then exits. Zeus Web Server processes the CGI header, adds any additional information required to the response (such as extra HTTP Headers or SSL encryption) and then passes this back to the client. Because the CGI scripts run as individual processes they can cause problems and consume excessive system resources if they receive unexpected input. CGI sandboxing enables you to limit the amount of resources that CGI processing can use on a per-virtual Server basis. Configuring API Support 219

222 Specifying CGI Configurables The CGI configurables are limits that are applied when the Virtual Server creates each CGI process, and so apply to every CGI script run by the Virtual Server 61. The following parameters specify options for the operating system's ulimit system call 62. Note that different operating systems implement this system call in different ways, and you should consult your operating system documentation to find out which ulimit options it supports. To use the default ulimit values, leave these configurables set to zero. To specify other values, set them in the following way: 6) Set Maximum CPU time to the maximum amount of CPU time that a process can run for. Use this to prevent any CGI script from monopolizing all the CPU. 7) Set Maximum address segment size to the maximum address space that each CGI process can use. This limits the total amount of memory that each process can use. Note that interpreted CGI scripts need larger limits than compiled CGI programs. 8) Set Maximum data segment size to the maximum data segment that each CGI process can use. This is the maximum amount of space that a process can use for its internal data structures, and so prevents a badly written CGI script using a large amount of memory. 9) Specify whether to allow the CGI process to fork, by clicking the appropriate forking option. 10) Click the Apply changes button to update your configuration. 61. Note that these options can also be overridden using.htaccess directives. This enables you to configure these options on a per-script basis (rather than a per-virtual Server basis). These are described in CGI Script Directives on page This means that you will not be able to specify limits that are less restrictive than those of the current user. This may therefore not behave as expected if you have not installed Zeus Web Server as the root user. 220 Configuring API Support

223 The following parameters specify further options that are not implemented using the ulimit system call. This means that they are platform independent. 1) Set Maximum elapsed time to be the maximum elapsed time that a CGI script can run for. When this is reached, Zeus Web Server issues a SIGTERM, followed by a SIGKILL every second, until the process dies. 2) Set Priority to the UNIX process priority that the CGI scripts will run at (note that lower values indicate higher priorities) 63. Running Multiple Scripts Concurrently Specify the maximum number of CGI scripts that this Virtual Server can run concurrently. Use this to ensure that no single web site can overwhelm the machine s resources by running a large number of scripts. Specify this in the following way: 1) Either specify the maximum number of scripts that can be run concurrently in the Max concurrent CGI scripts field, or enter 0 (zero) to specify no limit. 2) If the Virtual Server supports Subservers (see Configuring Subservers on page 253), then you can specify whether these limits are applied to the Virtual Server as a whole (the default) or whether they are applied individually to each Subserver. 3) Click the Apply changes button to update your configuration. Specifying the Security Configurables The security configurables enable you to configure greater security by specifying which user the CGI scripts are run as, and whether they are run chrooted. This enables you to specify a unique user for all the CGI scripts on the 63. Note that you cannot specify a higher priority than that of the process that the Zeus Web Server is running as. Configuring API Support 221

224 Virtual Server, which can help you monitor your system and analyze its performance. 1) Set the user that the CGI script is run as in one of the following ways: Set Run CGI scripts as owner of the requested file to specify that each CGI script should be run as the user who owns it. This allows scripts that have a handler defined to be run as the user who owns the script. For example, a Perl script will run as the script owner. Virtual Servers can be set up with multiple users who have their own CGI scripts in their home directories, and the scripts will run as the user id for each user. If the file is not a script called from a handler, then this option is identical to the next option. Note that if you set this option then you should ensure that the Virtual Server does not have any CGI scripts owned by root, for security reasons. Set Run CGI scripts as owner of the CGI executable to specify that each CGI script should be run by the owner of the executable. For example, this allows all Perl scripts to be run as the owner of the Perl executable defined as the handler. If you set this option then you should ensure that the Virtual Server does not have any CGI executables owned by root, for security reasons. Set Run CGI scripts as owner of the document root to specify that all CGI scripts should be run as the user who owns the document root. Note that you must also ensure that this is not root. 64 Set Run CGIs scripts as the specified uid/gid to specify that all CGI scripts should be run as the specified uid and gid. 65 If this is option is set, without specifying any values, then the CGI scripts are run as the user that Zeus Web Server is running as (configured during the installation process). 2) Click the Apply changes button to update your configuration. 64.Use this option on Subserver-enabled Virtual Servers to configure each Subserver s CGI scripts to run as the Subserver s document root owner. For more information about Subservers, refer to Configuring Subservers on page You can also set global (product-wide) limits for the minimum uid and gid that CGI scripts can be run as by setting the advanced CGI tunables. Refer to the support web site for more information about these. 222 Configuring API Support

225 Configuring chroot Jails You can configure the Virtual Server to run its CGI scripts chroot-ed by setting the Run CGI scripts chrooted radio button 66. This uses the chroot command to restrict CGI scripts to a specified part of the file system. If enabled, it means that the CGI scripts cannot access any files outside the chroot jail. By default, when you set this option, each CGI script is chroot-ed to its local directory. You can also configure explicit chroot jail directories to enable the scripts to be chroot-ed to a parent directory. If the chroot option is enabled and chroot jails are configured, then the Virtual Server checks whether any of the jail directories are parent directories of the CGI script before running it. If a jail directory is found that is a parent directory of the script, then the CGI is chroot-ed to that directory, otherwise it is chroot-ed to its local directory. If there are multiple parent jail directories then the directory with the longest matching prefix is used. For example, if a CGI script is in /usr/cgi/scripts, and the following chroot jails are configured: /usr and /usr/cgi, then the script is chroot-ed to /usr/cgi/. You can specify a chroot directory using a regular expression by prefixing it with a '~' as the first character of the directory name. In this case Zeus Web Server then interprets the remainder as a regular expression, and attempts to match it to the start of the CGI script path. If a match is found then this directory is used as the directory to chroot to. For example, a chroot directory of ~/home/[^/]+/ matches any directory /home/.../. For more information about specifying regular expressions, refer to Using Regular Expressions on page 389. Selecting the chroot option enhances security 67, but it needs to be set up carefully since it means that all the files that the CGI script needs to run must be available within the chroot jail. Specifically, CGI scripts often require 66. You must have installed Zeus Web Server as the root user to be able to chroot scripts. 67. This enhances security by reducing the environment that the application can see from being the entire machine to being just the domain that it needs in order to function. Configuring API Support 223

226 components such as interpreters or shared libraries, and so you may need to install a minimal root file system within the chroot directory. To configure the Virtual Server to use a chroot jail directory, simply enter the full path in the text box and click the Apply changes button. Zeus Web Server adds the chroot jail directory to the list of jail directories. i To remove an existing chroot jail from the list, click the delete check box and click the Apply changes button. Note: You can also configure chroot jails using the htaccess directives, chroot and chroot_dir (described in CGI Script Directives on page 346). Note that the htaccess settings override the settings in the Sandboxing CGI Scripts page Configuring Support for FastCGI Introducing FastCGI FastCGI is a language-independent, architecture-independent, scalable and open extension to CGI that retains all the benefits of CGI programs while eliminating its major weaknesses. It extends and enhances the CGI model in the following way: Applications can persist between client requests, reducing the start up overhead and enabling each application to maintain the request state between client calls. FastCGI does this using a persistent runner process that is used to handle multiple requests, so that the script effectively becomes a function call rather than a standalone binary, thus improving performance. Applications can reside on remote systems, which can be useful for distributing load and managing external web sites, and also means that 224 Configuring API Support

227 resource-intensive applications can be run on a separate machine to Zeus Web Server. As well as providing the traditional CGI 'responder' role (generating an HTTP response for an incoming HTTP request), FastCGI applications can provide the following: Filter functionality: Converting, parsing or formatting the requested file before returning it to the client. For example, a filter application could be mapped to the.sgml extension (MIME type of text/x-sgml), to convert SGML to HTML. If a user requests / the Virtual Server passes chap1.sgml as input to the application, which converts it and returns an HTML version to the requesting client. Authorizer' functionality: Implementing complex access control - based on criteria in the HTTP request header. For example, a client requests a particular URL that is passed to the authorizer FastCGI application. If the application grants authorization, it returns an HTTP response code of 200 (OK), and the request is passed on to another application to be processed - otherwise the request is not processed. FastCGI provides a straightforward migration path for CGI scripts by enabling you to migrate them easily, while providing inbuilt backward compatibility. Configure support for FastCGI applications by clicking the FastCGI link in the configuration page menu. Running FastCGI Applications FastCGI applications can be run using two different transport mechanisms: Local FastCGI applications can be run using UNIX domain sockets. This provides a simple and convenient way of configuring FastCGI applications to be started automatically when a request comes in. Zeus Web Server manages the local FastCGI applications. It starts them when required, using the sandboxing settings (user and group) you have Configuring API Support 225

228 configured. It runs as many instances of each FastCGI application as are required to service the load, up to the predefined concurrency limit. ZWS terminates FastCGI processes when they are no longer required. FastCGI applications can also be run over TCP/IP. This method must be used for remote applications and can also be used for local applications if required. In this case a destination host name and port is configured for the FastCGI application. A separate fcgirunner script is configured to listen on this port and is started on the remote host. When a request comes in, the fcgirunner script starts the FastCGI application. Comparing FastCGI with CGI The following table summarizes the differences between CGI and FastCGI applications: CGI Applications CGI suffers from inherent performance problems since a new process is created for each request and thrown away once the request has completed, resulting in poor efficiency. CGI can only supports a simple "Responder" role, in which the application generates the response that is returned to the client. The CGI interface uses operating system environment variables and pipes for communicating environment variables and input information. FastCGI Applications When a FastCGI program completes, the FastCGI process waits for the next request, rather than exiting. In addition to the traditional CGI 'Responder' role, FastCGI supports a Filter role, converting, parsing or formatting the requested file before returning it to the client, and an Authorizer' role, implementing complex access control - based on criteria in the HTTP request header. The FastCGI interface uses a TCP/IP connection for communicating environment variables and input information. This enables FastCGI programs to run remotely. 226 Configuring API Support

229 Further Information about FastCGI For more background information and an overview of FastCGI, refer to the API Examples and Documentation section at: In addition, refer to the FastCGI web site, at Enabling and Configuring FastCGI Support i Enable the Virtual Server s FastCGI support by clicking the appropriate radio button. You can then configure it to run FastCGI programs in the following way: Configure whether FastCGI programs can be run anywhere, as described on page 228. Configure the concurrency level used for run anywhere FastCGI programs, as described on page 228. Configure the user and group sandboxing settings for local FastCGI responders and authorizers, as described on page 229. Configure local FastCGI responder script directories, for responders on the local machine, as described on page 230. Configure remote FastCGI responders (responders on a remote machine), as described on page 231. Configure FastCGI authorizers on the local machine or on a remote machine, as described page 233. You can also configure additional FastCGI environment variables for local responder scripts, as described on page 235. Note: You must ensure that all your FastCGI program files have their executable flags set. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Configuring API Support 227

230 Restricting FastCGI Locations You can choose whether to enable FastCGI programs to run in any directory, or whether to confine them to specified directories. If they can be run from any directory then FastCGI programs are identified using the application/x-httpd-fcgi MIME type (typically associated with the.cgi or.fcgi file extension). Restricting FastCGI programs to specified directories provides additional security as you can then control access to these directories more tightly, and so can control who can write and modify the programs. This is often used in conjunction with local FastCGI responder directories (as described in Configuring Local Responder Script Directories on page 230) to enable programs to run in a directory that is outside the document root, thus providing even greater security. This is because you can then prevent users with write access to the document root from being able to write to the FastCGI directory. 1) Configure whether FastCGI programs are restricted or not by clicking the appropriate radio button. 2) Click the Apply changes button to update your configuration. Configuring FastCGI Concurrency Local FastCGI processes are started and stopped as required. The concurrency setting can be used to indicate to Zeus Web Server how many FastCGI processes it should run. For example, if a FastCGI process makes a slow database lookup, you may wish to run several processes in parallel so that you can perform several concurrent database lookups. A concurrency setting of 0 indicates that the FastCGI process manages its own concurrency. Zeus Web Server will only ever start up one FastCGI process (in this case, it is normal for the process to manage its concurrency by forking several children, or spawning several threads). A positive concurrency setting indicates how many FastCGI processes each ZWS child should run. Each child manages its own pool of processes, starting more processes when required (up to the concurrency limit) and terminating unused processes after a period of time. Each child manages the FastCGI 228 Configuring API Support

231 requests, and sends each new request to an idle FastCGI process, if one is available. Otherwise, it queues the request internally until a FastCGI process becomes available. i Note: This setting only applies to local FastCGI responders started as a result of the run from anywhere setting described in Restricting FastCGI Locations on page 228. Local FastCGI responders and authorizers started as a result of FastCGI directory mappings (Configuring Local Responder Script Directories on page 230 and Configuring Authorizers on page 233) have their own concurrency settings. Remote FastCGIs must manage their own concurrency. Configuring FastCGI Security Settings When a local FastCGI process is started, the security settings can be used to determine what user and group the FastCGI process should run as. Set Run FastCGI scripts as owner of the requested file to specify that each FastCGI script should be run as the user who owns the requested file. This setting is commonly used for FastCGI scripts that are registered as handlers for a different file type; for example, a PHP handler to handle.php files. If this setting is used, the FastCGI script will be run as the owner of the target file (for example, the.php file). This can be useful in a multi-user environment; many users can share the same handler application, but the application is run securely as the user who published the document. If the FastCGI is not started as a handler (for example, it is requested directly, or run as an authorizer), then this setting is identical to the next setting, Run FastCGI scripts as owner of the FastCGI executable. Set Run FastCGI scripts as owner of the FastCGI executable to specify that each FastCGI script should be run by the owner of the FastCGI Configuring API Support 229

232 executable. For example, this allows all PHP scripts to be run as the owner of the PHP executable defined as the handler. Set Run FastCGI scripts as owner of the document root to specify that all FastCGI scripts should be run as the user who owns the document root. Set Run FastCGI scripts as the specified uid/gid to specify that all FastCGI scripts should be run as the specified uid and gid. If this is option is set, without specifying any values, then the FastCGI scripts are run as the user that Zeus Web Server is running as (configured during the installation process). Configuring Local Responder Script Directories Local responders are FastCGI programs that run in a responder role in a local directory. The Virtual Server runs them from designated local responder directories by automatically starting the program when it receives its first request to it, and passing all subsequent requests directly to it (restarting it automatically on the next request that it receives if it exits) 68. Set up a local responder directory (from which local responders are run) by creating an alias to it in the following way: 1) Create a directory, such as /my_home/fastcgi-bin/. It is recommended that you create this directory outside the document root for greater security. 2) Specify the location where you want the directory to appear under the document root in the Map requests for field. This is the location that users will specify in a URL. An alias to a directory must end with a /. For example, specify /fastcgi-bin/ 68.If multiple Virtual Servers are configured to use the same local responder script then Zeus Web Server starts just one instance of the script, with the environment specified by the first Virtual Server to call it. 230 Configuring API Support

233 3) Specify the actual location of the local responder directory in the Map requests to field. This can be expressed in either of the following ways: As an absolute path, for example, /sales/pricelist/ As a path relative to the Zeus Web Server installation directory using %zeushome% to represent the installation directory. For example, specify /my_home/fastcgi-bin/. This means that all requests for items in /fastcgi-bin/ are automatically passed to /my_home/fastcgi-bin/ and run as FastCGI programs. 4) Specify the Concurrency that you would like to apply to FastCGI processes started from this directory mapping. See Configuring FastCGI Concurrency on page 228 for a detailed description of the meaning of the concurrency value. 5) Click the Apply changes button to update your configuration. Zeus Web Server adds the local responder directory to the list. You can now place programs, such as my_fastcgi, in /my_home/fastcgi-bin/. Users access and run it by entering the URL You can modify an existing local responder directory by doing the following: Modify its value by simply editing it and clicking the Apply changes button. Remove it by setting the Delete check box and clicking the Apply changes button. Configuring Remote Responder Script Directories Remote responders are FastCGI programs that run in a responder role on a remote machine. The Virtual Server runs them from designated remote responder directories and communicates with them using a TCP/IP connection. Running responders remotely can be helpful for reducing the load on your web server machine, and enhancing system performance Note that if processing many requests per second in this way, you may need to increase the number of ephemeral ports. Refer to your operating system documentation for more information about this. Configuring API Support 231

234 Set up a remote responder directory (from which remote responders are run) in the following way: 1) Create a directory on the remote machine, such as /my_remote_home/remote_fastcgi_bin/. 2) Specify the location where you want the remote responder to appear (under the document root) in the Directory name field. For example, enter /remote_fastcgi_bin/. 3) Configure the actual remote location of the remote responder directory in the following way: a) Enter the machine name (or IP address) of the remote machine on which the remote directory is located, in the Machine name field. b) Enter its port number in the Port field. 4) By default, remote responders support the standard HTTP methods. Specify whether the remote responder supports any additional HTTP methods, such as the WebDAV methods 70, by selecting the entry in the drop down box. 5) Click the Apply changes button. 6) Configure the actual location of the script on the remote machine as described in Configuring Remote Scripts to Start on page 235. i Note: You can also configure a remote responder to run on a local machine. This configures the Virtual Server to communicate with the responder using a TCP/IP connection, and enables multiple Virtual Servers to share the same responder. To do this, simply specify localhost in the Remote machine field. 70. For more information about Zeus Web Server support for WebDAV, refer to Configuring API Support

235 Zeus Web Server adds the FastCGI remote responder directory to the list. You can then do the following: Modify its value by simply editing it and clicking the Apply changes button. Remove it by setting the Delete check box and clicking the Apply changes button. Configuring Authorizers Authorizers authorize requests for URLs in particular subdirectories (rather than responding to requests for particular URLs). This means that to configure an authorizer you need to specify the directory for which it authorizes requests, and the path to the program itself (but you do not need to configure an aliased directory). If you are using a simple FastCGI authorizer to provide access to a web site, you can configure the Virtual Server to cache its responses so that the Virtual Server can re-use recent responses directly for subsequent requests from the same user. For example, when a user makes a request for a file in a protected part of the document root, the Virtual Server will return a response that states a username and password is required to be entered to access the resource. The user s web browser will prompt for username and password details and resubmit the request with the name and password specified. The Virtual Server then calls the authorizer with this information. The authorizer processes the request and tells the Virtual Server whether it should either allow or deny that user access. When this caching option is enabled then the Virtual Server caches the authorizer s decision for a specified timeout period with the same name and password. If the same user makes a subsequent request for a file in the document root during the timeout period, then rather than asking the FastCGI authorizer again, the Virtual Server simply reuses its previous decision. The FastCGI authorizer is not called again for that user until the user makes a request after the cache timeout has expired. Configuring API Support 233

236 This option is particularly useful if you have an authorizer that is authorizing access to the whole document root on a web site (rather than specifying different permissions for different directories) that is heavily used by a small number of users (such as an intranet). This is because although a user may be making many requests, the authorizer only needs to be called once during the cache timeout period, which leads to faster response times for the user and reduces the load on the machine running the FastCGI authorizer. Configure authorizers in the FastCGI Authorizers section of the FastCGI configuration page, in the following way: 1) Specify the path (relative to the document root) of the subdirectory for which the program authorizes requests, in the Authorized directory field. 2) Configure the location of the script in the Authorizer location field in one of the following ways: If the Authorizer is running locally, specify its full path (its location in the file system). If the Authorizer is running remotely, specify the machine name (or IP address) and port of the remote machine on which the remote directory is located, in the Remote machine field, in the format hostname:port. Configure the automatic startup of the program on the remote machine as described in Configuring Remote Scripts to Start on page ) To enable FastCGI Authorizer caching, set the Cache responses check box to Yes. 4) Specify the Concurrency that you would like to apply to local FastCGI authorizers started from this directory mapping. See Configuring FastCGI Concurrency on page 228 for a detailed description of the meaning of the concurrency value. 5) Click the Apply changes button to apply the change. Zeus Web Server adds the authorizer to the list of authorizers. 234 Configuring API Support

237 You can modify existing authorizers in the following way: To remove an authorizer, click the Delete check box and click the Apply changes button. To modify the directory or location of the authorizer, simply edit the field and click the Apply changes button to apply the change. Configuring Remote Scripts to Start! Zeus Web Server is not able to start remote responders and authorizers automatically. They must therefore be started using the $ZEUSHOME/web/bin/fcgirunner script. This script is written in Perl so that it can be run on most platforms. Simply ensure that Perl5 is installed on the remote machine and copy the script over (to any directory). Start fcgirunner specifying the port number to listen on (configured when setting up the remote script), and the full path name of the FastCGI program. fcgirunner then runs, listening to requests for the specified script, and starts it up when it receives one. Warning: The fcgirunner script starts the FastCGI programs as the same user that it is started as. It is therefore recommended that you use a port number greater than or equal to Configuring Additional FastCGI Environment Variables The FastCGI interface passes all the standard CGI/1.1 environment variables to the FastCGI application (providing access to information such as the location of the client and its browser type). This is the case for all FastCGI applications, whether they are local or remote. If you have configured any local FastCGI responders or authorizers, you can specify extra environment variables which are passed to it on startup. Do this in the following way: 1) Enter a name for the new environment variable in the Name field. 2) Enter its value in the Value field. Configuring API Support 235

238 3) Click the Apply changes button. i Zeus Web Server adds the environment variable to the list of configured environment variables. You can then do the following: Modify its name or value by simply editing it and clicking the Apply changes button. Remove it by setting the Delete check box and clicking the Apply changes button. Note: To set up additional environment variables for remote FastCGI programs (that is, FastCGI programs that are running over TCP/IP), you can specify them from the command line when you start the fcgirunner script. The FastCGI program then inherits them from the fcgirunner environment Configuring ISAPI Support Introducing ISAPI ISAPI provides a vendor-independent, open standard API that you can use to extend your web site s functionality, while providing greater flexibility and better performance than CGI scripts. ISAPI was originally proposed by, and is still backed by, Microsoft. It is, however, designed to be an open standard that anyone can implement and use. ISAPI modules are written in C and compiled into a binary shared library (or DLL). They implement callback functions that the Virtual Server calls when processing HTTP requests. ISAPI supports two types of modules: Extensions are called by the Virtual Server when it receives a request for a particular URL. Filters are called by the Virtual Server when any request (for any URL) reaches specified stages of processing. 236 Configuring API Support

239 In the simplest terms, extensions generate content and filters modify requests. ISAPI defines a standard set of callback functions that a web server must implement, but because the standard is open, specific products can also implement additional functions. This section outlines just the basic, mandatory functions. Configure support for ISAPI modules by clicking the ISAPI link in the configuration page menu. Introducing ISAPI Server Extensions An ISAPI server extension is an ISAPI module that is called using a particular URL, and processes requests by generating the page content. ISAPI server extension modules are located in directories that are configured as ISAPI extension directories. They are generally used to enhance the capabilities of the Virtual Server. An ISAPI Extension module is implemented using the following functions: GetExtensionVersion registers the ISAPI extension with the Virtual Server, so that it can subsequently call the associated HttpExtensionProc, and tell it which ISAPI version the extension supports. HttpExtensionProc implements the request processing functionality. When the extension URL is requested, the Virtual Server runs the HttpExtensionProc, which generates the output to send to the browser. HTTP request information is passed between the Virtual Server and the extension using the EXTENSION_CONTROL_BLOCK structure. Introducing ISAPI Filters An ISAPI filter is a module that registers to receive all requests that reach specified stages of processing. The Virtual Server then calls it with information about the current request, so that it can perform additional request filtering before returning the request to the Virtual Server. ISAPI filters can be used to monitor and change the request data. Configuring API Support 237

240 An ISAPI Filter module is implemented using the following functions: GetFilterVersion registers the ISAPI filter with the Virtual Server, and tells it which notifications the filter wants to receive (that is, at which points during HTTP request processing, the filter is to be called). A filter module can register for multiple notifications, and multiple filter modules can register for any given notification. The module can also specify at which priority it is registering for a notification: the filter registered with the highest priority is notified first. HttpFilterProc implements the request filtering functionality. The Virtual Server calls this when a request reaches the stage in processing that the filter registered for so that it can filter the request further. The filter can then specify whether the request should be passed on to any other filters that have registered for the same notification, or whether the Virtual Server should continue processing the request. ISAPI filters are typically used to provide enhanced logging of HTTP requests (for example, to track who is logging on to your web site), custom encryption, custom compression, or additional authentication methods. Running ISAPI Applications In-Process and Out-of-Process ISAPI Filters and extensions can run in-process and out-of-process. In-process filters or extensions are loaded into, and run in, the same process space as the Virtual Server. This means that they are more efficient, but can affect the Virtual Server s stability and security. Modules that have high latency (that are I/O intensive or have long processing cycles, such as content generators that retrieve data from an external source) could also affect the Virtual Server performance because it is unable to continue processing further requests until the in-process ISAPI module has finished processing. Out-of-process filters or extensions run in a separate process to the Virtual Server, and are controlled by a separate process called the ISAPI runner. These are less efficient but provide greater protection to the Virtual Server because if they prove to be unreliable or insecure only the ISAPI runner process is affected and not the Virtual Server process. 238 Configuring API Support

241 Comparing ISAPI with CGI ISAPI modules are written in C and compiled as shared objects (that is, dynamic libraries or DLLs). This gives them a considerable performance advantage but means that each module must be compiled individually for each platform that it is run on. ISAPI modules can be run in-process or outof-process. Depending on circumstances, ISAPI modules can perform 5 to 10 times faster than conventional CGI applications Each CGI script, on the other hand, implements just one command, contained in its own executable file. Each new CGI request launches a new process. Further Information about ISAPI For more background information, and an overview of ISAPI, refer to the API Examples and Documentation section at: In addition provides more detailed reference information about the API. The ISAPI developer web site can be found at For detailed API information, refer to the Zeus Web Server man pages. In particular refer to man isapi 71 for an overview of the API, and a list of the other ISAPI man pages that are available. 71. For more information about the Zeus Web Server man pages, refer to Viewing Zeus Web Server Man Pages on page 370. Configuring API Support 239

242 Enabling and Configuring ISAPI Support Enable the Virtual Server s ISAPI support by clicking the appropriate radio button. You can then configure it to run ISAPI modules in the following way: You can configure ISAPI extension directories, as described on page 240. You can specify whether extensions run in-process or out-of-process, as described on page 241. You can configure ISAPI filters that run in-process, as described on page 241. You can configure ISAPI filters that run out-of-process, as described on page 242. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Configuring ISAPI Extension Directories ISAPI extensions are called using a particular URL and are located in directories that are configured as ISAPI extension directories (see Introducing ISAPI Server Extensions on page 237). Configure ISAPI extension directories in the following way: 1) Create a directory, such as /my_home/isapi-bin/. It is recommended that you create this directory outside the document root for greater security. 2) Specify the location where you want the directory to appear under the document root in the Map requests for field. This is the location that users will specify in a URL. An alias to a directory must end with a /. For example, specify /isapi-bin/ 240 Configuring API Support

243 3) Specify the actual location of the extension directory in the Map requests to field. This can be expressed in either of the following ways: As an absolute path, for example, /sales/pricelist/ As a path relative to the Zeus Web Server installation directory using %zeushome% to represent the installation directory. For example, specify /my_home/isapi-bin/. This means that all requests for items in /isapi-bin/ are automatically passed to /my_home/isapi-bin/ and run as ISAPI extensions. Configuring In-Process and Out-of-Process Extensions Specify whether the ISAPI extensions should be run in-process or out-ofprocess by clicking the appropriate check box. For more information about this, refer to Running ISAPI Applications In-Process and Out-of-Process on page 238. Registering In-Process ISAPI Filters Register an in-process ISAPI filter, using the Registered In-Process Filters section, in the following way: 1) Specify the full path and file name of the in-process filter s compiled shared object (DLL) in the Full path field. 2) Click the Apply changes button. Zeus Web Server adds the filter to the list of in-process filters. You can then do the following: Modify its name by simply editing it and clicking the Apply changes button. Remove it by setting the Delete check box and clicking the Apply changes button. Configuring API Support 241

244 Registering Out-of-Process ISAPI Filters Register an out-of-process ISAPI filter, using the Registered Out-of-Process Filters section, in the following way: 1) Specify the full path and file name of the out-of-process filter s compiled shared object (DLL) in the File field. 2) Click the Apply changes button. Zeus Web Server adds the filter to the list of out-of-process filters. You can then do the following: Modify its name by simply editing it and clicking the Apply changes button. Remove it by setting the Delete check box and clicking the Apply changes button Configuring Java Servlet Support Introducing Java Servlets Java servlets can be thought of as Java applets that run on the web server, rather than on the client (browser). They are executed from within a Java Virtual Machine (JVM) and enable you to run multi-threaded, object oriented, portable web server applications that can receive and respond to requests from web clients. Servlets provide an open-standard, component-based, platform-independent method for building web-based applications. They can retain state information that persists over multiple requests, which means that they are ideal for implementing database-backed web sites. JSP (Java Server Pages) are an extension of the servlet technology that integrates with HTML and XML pages, enabling you to integrate fixed or static template data with dynamic content. They enable you to create dynamic pages that are platform and server independent. 242 Configuring API Support

245 Configure support for Java servlets by clicking the Java Servlets link in the configuration page menu. Introducing the Virtual Server s Java Servlet Support The Virtual Server can support servlet servers that implement Sun s Java Servlet API, and that communicate with the Virtual Server using the AJP (Apache JServ protocol), such as JServ and Tomcat. Java servlet servers manage and invoke Java servlets. The servlet server runs the servlets in a JVM that is separate to Zeus Web Server. The Virtual Server communicates with the servlet server using TCP/IP sockets and passes it incoming requests for designated directories. The Virtual Server can be configured to run the Java servlet server either locally or remotely. Running the servlets remotely enables you to configure the JVMs to run on dedicated machines that are optimized for Java, resulting in both increased performance and system robustness Enabling and Configuring Java Servlets Support Enable the Virtual Server s Java Servlet support by clicking the appropriate radio button. Once you have enabled the Virtual Server s Java Servlets support, you can configure it to run servlets by configuring mount points, as described in the following section. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Adding a Java Servlet Mount Point Servlet servers can manage many servlets. These can be grouped into contexts (previously known as zones ) using the servlet server. Each context identifies and configures a set of servlets by specifying the locations of its servlets, whether the classes are automatically reloaded when they are changed, and so on. For more information about contexts, refer to your servlet server documentation. Configuring API Support 243

246 Configure the Virtual Server to support a JServ context (or zone) in the following way: 1) Specify the path (relative to the document root) of a directory in the Directory field. The Virtual Server passes all requests for this subdirectory to the servlet server. 72 2) Specify the machine name of the machine running the servlet server in the Machine name field. Enter localhost if it is running on the local machine. 3) Specify the port number of the servlet server in the Port field. Note that the default port for the JServ and Tomcat servers is port ) Specify the servlet context (known as a zone in earlier versions of the JServ program) in the Servlet context field. 5) Set the Protocol field to the version of the Jserv Protocol that the Virtual Server should use to communicate with the servlet server. Set this to the version of the Jserv protocol that the vendor of your servlet server recommends. If you are running a version of JServ earlier than or including JServ 1.0, set this to ajpv11. If you are running JServ 1.1 (or a more recent version) or Tomcat, then set this to ajpv12 (or above). Accessing Servlets Once you have set up a mount point, users can access servlets by specifying the mount point and the servlet name in the following way: For example, if you added a mount point of /jserv then you could access a servlet called HelloWorld by entering the URL Servlets with fully qualified class names are accessed in a similar way. For example, access a servlet called com.mysite.jserv.example1 using 72.This is just like configuring an alias directory for a CGI script. 244 Configuring API Support

247 For more information about running Tomcat and JServ using Zeus Web Server, refer to the Zeus support web site Configuring NSAPI Support Introducing NSAPI NSAPI is Netscape s proprietary web server API. It provides a programming interface that enables NSAPI applications to augment core request processing functionality. NSAPI applications are web server plug-ins that are loaded and invoked during different stages of the HTTP request processing. They are written in C or C++. The Virtual Server can load and run NSAPI applications, by providing a binary compatible NSAPI emulation of NSAPI v3.0 and v4.0. This enables you to migrate existing NSAPI applications seamlessly to Zeus Web Server. Configure support for NSAPI applications by clicking the NSAPI link in the configuration page menu. Overview of the NSAPI Interface NSAPI provides an interface for implementing Server Application Functions (SAFs) - the functions that provide Netscape Enterprise Server s core request processing functionality. Each SAF belongs to a particular step in the request processing sequence. It is configured individually and can access the request data, and any web server variables. Each runs when a set of specified conditions are met and generates a return code indicating whether it succeeded, did nothing, or failed to process the request. This tells the web server whether to continue with the next SAF in the current step, move on to the next step or abort the request. NSAPI applications implement custom SAFs. Configuring API Support 245

248 Enabling and Configuring NSAPI Support This section summarizes how to configure support for NSAPI applications. Enable the Virtual Server s NSAPI support by clicking the appropriate radio button. You can then configure it to run NSAPI applications in the following way: Specify the NSAPI configuration file directory (see Configuring the NSAPI Configuration File Directory on page 246). Optionally specify the user and group that NSAPI applications will be run as (see Configuring NSAPI Sandboxing on page 247). Run the installation script for your NSAPI application. It will probably ask you for the location of your obj.conf file, or your configuration directory. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Configuring the NSAPI Configuration File Directory NSAPI applications specify their NSAPI configuration information in three text-based configuration files that are held in a configuration directory: The object configuration file, obj.conf is the master file that configures and initializes each of the SAFs. It is case-sensitive, and sensitive to white space. magnus.conf contains one or more LoadObjects keys, that identifies which obj.conf to use, but is otherwise empty. mime.types specifies NSAPI application-specific MIME types. It specifies how file name extensions are mapped to HTTP content-type, contentencoding and content-language. Note that the MIME types specified in this file override those configured in the Virtual Server s MIME Types page. NSAPI applications expect to find the basic set of Netscape configuration files when they are installed. This means that if you are installing the first NSAPI application on the Virtual Server, you need to create a default set of configuration files. You can then run the application s installation process and 246 Configuring API Support

249 provide it with the location of this set of configuration files so that it can modify them appropriately. (If you already have an existing NSAPI application installed then you will not need to do this, just enter the existing configuration file location.) You can then install your application, and the installation process adds the parameters it needs to the files. To create a skeleton set of configuration files, click the links on the web page to view the sample files (obj.conf, mime.types and magnus.conf 73 ). You can then save them to an appropriate location. Use this section to specify the directory in which these files are located. Note that they must always be placed in a directory named path_prefix/https-virtual_server_name/config/ (where path_prefix can be any path). i Note: Enter the path_prefix directory in the Configuration directory tree field. Click the Apply changes button. Configuring NSAPI Sandboxing In most cases you will have configured Zeus Web Server to start as root (this is the default option during the installation process). In this case you can configure greater security by specifying the uid and gid that the NSAPI applications will run as. This enables you to specify a unique user for all the NSAPI applications on the Virtual Server, which can help you monitor your system and analyze its performance. Do this in the following way: 1) Specify the user that you wish NSAPI applications to run as in the uid field. 73. For more information about the format and content of these files, refer to the API Examples and Documentation section at: Configuring API Support 247

250 2) Specify the group that you wish NSAPI applications to run as in the gid field. 3) Click the Apply changes button. i Note: If you do not configure these options then NSAPI applications are run as the user that Zeus Web Server is running as (configured during the installation process). The NSAPI Runner NSAPI applications are run in an external, multithreaded runner called zeus.nsapi. There is one instance of this runner for each Virtual Server that has NSAPI functionality enabled. The runner maintains a pool of threads to service NSAPI requests Configuring Support for the ZDAC API Introducing ZDAC The ZDAC (Zeus Distributed Authentication and Content) API can be thought of as providing a simpler, more lightweight version of the functionality provided by the FastCGI interface. This API enables the Virtual Server to communicate with separate authorizers and content generation servers over a TCP/IP socket interface. These can be implemented in any programming language that supports BSD sockets. You can configure the ZDAC server to run on the same machine as the Virtual Server, or on a remote machine. It enables you to centralize authentication and content generation across multiple Virtual Servers, on any networked machine while providing location and language independence. Configure support for ZDAC applications by clicking the ZDAC link in the configuration page menu. 248 Configuring API Support

251 Introducing the ZDAC Authentication API The ZDAC Authentication API can be used to delegate access control policies for specified sections of the document tree. It can be used, for example, to authenticate all requests to a web site by performing SQL lookups on a central database. When the Virtual Server receives a request for a file in an authenticated directory, it passes the following information to the authorizer: The host name or IP address of the client making the request The requested URL The HTTP method used (GET or POST and so on) The username and password (if specified) A cookie (if included) The authorizer processes this information and determines whether the specified user is allowed access to the specified URL (by checking the details against a separate authentication database, if necessary). The authorizer then does one of the following: It requests the user to supply a password (if no password was supplied or if it was incorrect). It denies access to the page (in which case the Virtual Server returns an HTTP error page). It permits access to the requested page (in which case the Virtual Server simply returns this page). Introducing the ZDAC Content API The ZDAC content API can be used to generate pages dynamically. Configuring API Support 249

252 When the Virtual Server receives a request for a file in one of the designated ZDAC directories, it passes the following information to the specified server: All the standard CGI environment variables. The data supplied with a POST request or the arguments supplied to a GET request. The content generator processes the information and returns the generated page to the Virtual Server, which returns it to the client. Further Information about ZDAC For more background information, and an overview of ZDAC, refer to the API Examples and Documentation section at: Enabling and Configuring ZDAC Support Enable the Virtual Server s ZDAC support by clicking the appropriate radio button. Once you have enabled the Virtual Server s ZDAC support, you can configure it to run ZDAC servers in the following way: Specify the ZDAC content directory, as described on page 250. Configure ZDAC content generators, as described on page 251. Configure ZDAC authorizers, as described on page 251. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Specifying the ZDAC Content Directory The ZDAC content directory is the directory, in the document root, for which all requests are passed to the specified content generator 74. Specify the name of this directory, relative to the document root, in the ZDAC directory field. Click the Apply changes button. 74.This can be thought of as an aliased directory. 250 Configuring API Support

253 Configuring a Content Generator To configure a content generator, do the following: 1) Specify the name of the content generator in the Generator name field. 2) Specify the location of the machine on which the content generator is running in the Host name field. To specify the local machine, enter localhost. 3) Specify the port in the Port field. 4) Click the Apply changes button. Zeus Web Server adds the content generator to the list of content generators. You can then do the following: Modify its machine location by simply editing the machine name and port values and clicking the Apply changes button. Remove it by setting the Delete check box and clicking the Apply changes button. The content generator is then accessed by specifying /zdac_directory/generator_name in a URL. Configuring an Authorizer To configure an authorizer, do the following: 1) Specify which directory (relative to the document root) you want the authorizer to authenticate requests for, in the Authorized directory field. 2) Specify the location of the machine on which the authorizer is running in the Host name field. To specify the local machine, enter localhost. 3) Specify the port in the Port field. 4) Enter the text to be displayed to the user when they are asked to enter their username and password, in the Realm field. This could, for example, describe the information that they are asking for, such as Enter username and password to see latest sales figures. 5) Click the Apply changes button. Configuring API Support 251

254 Zeus Web Server adds the authorizer to the list of authorizers. You can then do the following: Modify its machine location or realm text by simply editing the value and clicking the Apply changes button. Remove it by setting the Delete check box and clicking the Apply changes button. 252 Configuring API Support

255 CHAPTER 12 Configuring Subservers 12.1 Introduction Subservers provide an easy way of configuring, supporting and managing thousands of similarly configured web sites. Each Subserver is an individual web site with its own host name and document root, and has the same configured functionality as the Virtual Server that supports it. One Virtual Server can support any number of Subservers, and all of them can be configured and managed just by configuring and managing the Virtual Server. Subservers make it simple to set up multiple web sites configured with the same functionality whilst avoiding the memory and disk usage overheads of running hundreds of Virtual Servers. They are extremely easy to manage, as they can be created and deleted on-the-fly, without any affect on other running web sites. Subservers are typically used by hosting companies who want to support thousands of web sites that are all configured in the same way. The hosting company can change the configuration of all the web sites simply by changing the configuration in one place. Subservers can be used to support web sites that all share the same domain name, such as and or web sites with totally independent names, such as and This chapter describes how to set up and use a Virtual Server that supports Subservers and the different Subserver directory structures that you can use. Configuring Subservers 253

256 12.2 Concepts Once a Virtual Server has been set up to support Subservers, each Subserver is added to the Virtual Server by simply creating a subdirectory within the Virtual Server s document root. Each subdirectory is named with the Subserver s web site host name (in lowercase), and holds the web site content. For example, to create the web site make a subdirectory called Due to operating system limitations, it may not be possible to create all the required subdirectories within one directory. For this reason, different subdirectory structures can be used to scale the number of Subservers that can be added to a Virtual Server. This section describes different ways of building large directory structures easily. Subserver Directory Structure When configuring a Virtual Server to support Subservers, it is important to decide on the layout of the Subservers directories within the Virtual Server s document root before creating any directories. This is because changing a large directory structure is a complex task. By default, all the subdirectories are located directly in the document root, but this arrangement may not be practical in some circumstances: Your operating system may have a fixed limit on the maximum number of subdirectories allowed in one directory, making it impossible to house them all directly in the Virtual Server s document root. Your operating system may not have a fixed limit, but its performance may suffer badly when large numbers of subdirectories are placed in one directory. You may have a legacy system of web site directories, and want to map Subservers onto them, without relocating them. To overcome these problems, Zeus Web Server enables you to specify which directory structure is used. Whichever one you specify, it is your responsibility to create the necessary directories, and place the Subservers web site content in the correct places. 254 Configuring Subservers

257 The possible directory structures that you can use are: Standard layout (the default) Each Subserver directory is placed directly in the Virtual Server s document root. This layout is extremely easy to use, but is only recommended if you have less than a thousand Subservers (due to limitations of the operating system) Document root Simple multi-directory layout This layout avoids having a large number of subdirectories in one location. It uses a system of subdirectories, nested three levels deep, in order to ensure that no one directory contains too many subdirectories. The first two levels of subdirectories have single character names, taken from the first and second letters of the Subservers host names (ignoring any www. part). The Subservers document root directories are located at the third level, and each directory is located below the directory branch corresponding to the first two letters of its name. For example, the Subserver would be located at: virtual-server-docroot/m/y/ and the Subserver support.mysubserver.com would be located at: virtual-server-docroot/s/u/support.mysubserver.com Configuring Subservers 255

258 Any Subserver with just one letter in its name is located in the /a/a directory. Document root m z y e This layout enables thousands of Subserver directories to be accommodated, without ever having too many in any one directory. It is easy to work with, because although the Subserver directories are distributed within a complicated directory tree, it is simple to work out where each directory is located. However, if there are many Subservers with names that start with the same two letters, these will all end up in the same place, defeating the system. Note that as you add Subservers, it is up to you to create the necessary parts of the directory structure, and place the new directories in the correct places. Complex multi-directory layout This layout is similar to the simple multi-directory layout, but uses nested subdirectory names of two characters in length. The names are derived by performing a hashing function on the Subserver directory name, and so have no apparent relationship to the name. For example, a Subserver 256 Configuring Subservers

259 called would be located in the directory virtual-server-docroot/qv/94/ Document root NO JB TM S0 uh 7l To work out where to create a document root directory, use the subserver_hash.pl script, located in $ZEUSHOME/webadmin/bin. Run the script with the Subserver host name. It returns the directory path for the Subserver, relative to the Virtual Server s document root. For example, the command:./subserver_hash.pl returns: TM/7l/ The complex multi-directory layout is more efficient than the simple layout, because it generates different directories even when many Subservers have similar names. This results in far fewer Subserver directories being located in the same directory, and therefore eliminates problems with operating system limitations. However, it is more complicated to use because you need to use the hashing function to determine the Subserver s directory. Custom Subserver Map Function The Custom Subserver Map Function enables you to map Subservers document roots onto existing web site directories. To use it, write a C program to perform the mapping from Subserver host name to directory location. For information on how to create this C program, see Using a Custom Subserver Mapping Function on page 262. Configuring Subservers 257

260 Directory Structure Prefix and Suffix As well as specifying a directory structure layout, it is possible to configure a prefix and suffix, which are used in conjunction with the directory structure to determine where Subserver document root directories are located. The prefix and suffix enable you to configure a more convenient directory structure by inserting an extra directory level between the Virtual Server s document root and the Subserver document root directory. This can be useful if you want to store additional data related to a Subserver alongside the Subserver document root, but not actually in it. Specifying a prefix and/or suffix changes the location of Subserver document root directories, as follows: The prefix is treated as a subdirectory of the Virtual Server s document root. For example, if you specify a prefix value of html, and are using the simple multi-directory layout, then the Subserver would have a document root located in: virtual-server-docroot/html/s/u/ The suffix is treated as a subdirectory of the Subserver s document root. For example, if you specify a suffix value of html, and are using the simple multi-directory layout, then the Subserver would have a document root located in: virtual-server-docroot/s/u/ Creating Subservers To create a Subserver, start by creating a Virtual Server, then configure it to support Subservers by doing the following: 1) Access the Subservers page by clicking the Subservers link in the configuration page menu. 2) Enable Subserver functionality by clicking the appropriate radio button. 3) Select a Directory Structure. The default setting is Standard Layout, where all the Subserver directories are located directly in the Virtual Server s document root. It is important to select the appropriate directory 258 Configuring Subservers

261 structure at this point because it cannot be changed later without rearranging all the Subservers web site directories. For information on how to choose a directory layout, see Subserver Directory Structure on page ) Optionally specify a Directory Structure Prefix and Suffix. For more information on these, see Directory Structure Prefix and Suffix on page ) Click the Apply changes button. i Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Note: Once you have configured a Virtual Server to have Subservers, there is no longer a link from the Virtual Server s domain name on the Virtual Server status page to its web site. This is because the Virtual Server could potentially be running many web sites Using Subservers Publishing a Web Site on a Subserver To publish a web site on a Subserver, create the Subserver s document root directory, named with the Subserver s host name, and place its web site content there. There is no need to use the web-based user interface; simply creating the directory creates the Subserver. The Subserver directory name must be the full host name of the Subserver, but in lowercase. This is because host names are case-insensitive and so Zeus Web Server treats all host names as if they were in lowercase. For example, to create a Subserver with the host name make a directory named The location of the Subserver s document root depends on the directory structure that you selected when configuring your Virtual Server. If you chose the simplest case of the Standard Layout with no prefix or suffix, create the Configuring Subservers 259

262 directory in the Virtual Server s document root. If not, consult the section Subserver Directory Structure on page 254 for information on where to create it. Once you have configured a Virtual Server to have Subservers, and have created a Subserver by making its web site directory, the Subserver will automatically be running. However, users will not be able to view the web site content you place there until you have configured the DNS to direct requests to the Subserver, as described in the following section. Configuring the DNS for Subservers To configure the DNS to support Subservers, make an entry in the DNS table that resolves each Subserver s name to the IP address of the machine it is running on. If the Subservers have completely independent names, make one DNS entry for each Subserver. If the Subservers host names all share a common domain name, make a single entry in the DNS, resolving them all to the same IP address. For example, if your Subservers are named myhost.isp.com and yourhost.isp.com, make a DNS entry resolving *.isp.com to the IP address of the machine they are running on. Viewing a Subserver s Web Site To view a Subserver s web site, enter its host name and port number into your browser, exactly as you would for a Virtual Server. The Subserver s port number is the same as the port number of the Virtual Server that supports it. Deleting a Subserver To delete a Subserver: 1) Remove its entry from the DNS, so that it no longer receives requests. 2) Delete its web site content and document root directory. 260 Configuring Subservers

263 12.5 Advanced Subserver Configuration Enabling Default Subservers You can configure what happens when Zeus Web Server receives a request for a web page on a Subserver that does not exist. By default, the user receives the standard HTTP 404 error message, telling them that the page could not be found. You can create special default Subservers, with wildcard characters in their names, and configure Zeus Web Server to attempt to return the requested page from one of these Subservers. i i For example, suppose a user requests when this Subserver does not exist. If you have configured Zeus Web Server to pass requests to default Subservers, it then looks for a Subserver called *.sales.myhost.com (that is, it replaces the first part of the host name with a * character). If it finds it, it returns page1.html from its document root. If not, it then looks for a Subserver called *.myhost.com, and failing that, one called *.com. If neither of these can be found, it finally looks for a Subserver called *. Note: To create a directory that starts with a wildcard character, use the command mkdir \*.subserver.com Note: If you are using the Simple multi-directory layout scheme for your subservers, the default subserver(s) should be placed in a directory named a/a/. Automatic Webmaster Address If you want the webmaster address (displayed on the HTTP error pages) to be customized for each Subserver, switch on the Automatic Webmaster Address option in the Subservers configuration page. The address that appears on error pages then takes the format: name@subserver_domain_name, where name is taken from the username that you enter. Configuring Subservers 261

264 If you do not enable this option, the address is taken from Virtual Server s general configuration, so HTTP error pages for all Subservers will have the same webmaster address on them. For more information about the Virtual Server s General Configuration, see General Configuration Information on page 95. For more information about configuring the HTTP error pages, see Error Handling on page 173. Using a Custom Subserver Mapping Function Custom Subserver mapping enables you to implement any function for mapping a Subserver name to a directory structure. You do this by writing and compiling a DSO (Dynamic Shared Object) containing a C function to perform the mapping. You then specify its location within the Subservers configuration page. The default location is $ZEUSHOME/web/bin/subserver_map.so, but you are recommended to store it outside the $ZEUSHOME directory, so that it does not get overwritten if you upgrade your Zeus Web Server software. The DSO which contains the mapping function needs to contain a custom_subserver_map symbol defined as: void custom_subserver_map( const char *host, const char *docroot, char *buffer, int buffsz; SubserverCallTable *ct ); The following table summarizes how to use each of the parameters in this function: Parameter Usage host docroot The host header in lowercase, with the port stripped off. The Virtual Server s document root. 262 Configuring Subservers

265 Parameter Usage buffer buffsz ct You should fill buffer with the Subserver s document root, relative to the Virtual Server s document root. For example, if your Virtual Server has a document root of /disk2/ and you want a the Subserver s document root to be /disk2/myisp.com/d/o/c/doc, then put myisp.com/d/o/c/doc in the buffer. You should not put more than buffsz bytes in the buffer. The maximum number of bytes allowed in the buffer. ct points to a vector table which is defined as: typedef struct { int (*cstat)( const char *file, int flen, struct statinfo * ); } SubserverCallTable; This enables you to call the Zeus Web Server cached stat routine should you wish to do so. The semantics are the same as UNIX stat, except that the result is cached for speed (but could be out of date), and a smaller stat structure is used. A statinfo structure is defined as: struct statinfo { int mtime, ctime; // modify, creation int size; // file size int mode; // flags int uid, gid; }; Once you have written and compiled your C program, integrate it into the Virtual Server in the following way: 1) Access the Subservers page by clicking the Subservers link in the configuration page menu. 2) In the section Using a Custom Subserver Mapping Function, enter the full path and name of your C program. 3) Click the Apply changes button. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Configuring Subservers 263

266 Using Subservers with Older Browsers Zeus Web Server s subservers require all requests for web pages to be in HTTP/1.1 format. This means that every request is accompanied by a host header that enables Zeus Web Server to work out which Subserver the request should go to. Some older browsers may not send this header with their requests, in which case they will not be able to access web site content running on Subservers. If Zeus Web Server encounters a request from one of these older browsers, it attempts to find the requested web page on a Subserver called _default. If you create a Subserver with this name, it can be used to return a polite notice to the user, suggesting that they upgrade their browser. Request Logging for Individual Subservers If you are using Subservers, the request logging information for all the Subservers is held in the request log file of their Virtual Server. If you want to analyze the request log information for individual Subservers, it may be more convenient to split the log file into separate files, one for each Subserver. You can then delegate access to this file to the webmaster for each Subserver. For information on splitting the log file into separate files, see The subserver_logsplit.pl Script on page 378. For information on how to set up request logging, see Configuring Request logging on page 165. CGI Logging for Individual Subservers If your Subservers run CGI scripts, then by default any error output from the scripts is logged to the Virtual Server s error log file. If you want the error output to be logged to individual files for each Subserver, switch on sitespecific CGI error logging. For information on how to do this, see Configuring CGI Error Logging on page Configuring Subservers

267 12.6 Using Global.htaccess with Subservers Using htaccess Files on page 199 describes how to modify the configuration of a virtual server by placing special configuration files in the docroot of a web site. This can also be used to make modifications to the configuration of an individual subserver. Some configuration changes can only be made in a global htaccess file (see Supported Directives on page 327). You can create a global.htaccess file for an individual subserver, which is considered in addition to the primary global.htaccess file. When a Subserver connection is received by the server, the htaccess module will consider both the global.htaccess file, and the global.htaccess file with the name of the Subserver appended to it to be a single logical file. For example, if you have a global.htaccess file of /usr/local/web/global.htaccess and a subserver named and you are using the standard filesystem layout, the htaccess module will look at both of the following files, in order: 1) /usr/local/web/global.htaccess 2) /usr/local/web/global.htaccess. If you are using a different filesystem layout, the server will look at global.htaccess./<mapped filename> instead. For example, in the case of with the Simple multidirectory layout, the server will look at the following file: /usr/local/web/global.htaccess./s/u/ In the subserver global.htaccess file you can set any directives that you can in the normal global.htaccess file. In this way, any setting that can be configured with global.htaccess files can be overridden for particular Subservers. This also has the added advantages that any changes to the global.htaccess files are automatically reloaded by the web server, allowing easy real-time server alterations by scripts. Configuring Subservers 265

268 266 Configuring Subservers

269 CHAPTER 13 Configuring Add-Ons 13.1 Introduction Zeus Web Server integrates easily with a number of add-ons and third party products that provide extra functionality for web site users: You can configure each Virtual Server to use the search engine. This enables users to search the Virtual Server s web site. For more information about how to configure and implement the search engine for a Virtual Server, refer to Configuring the Search Engine on page 267. To provide support for NCSA server-side imagemaps, refer to Configuring Server-Side Imagemaps on page 274. You can configure each Virtual Server so that its web site administrators can use Microsoft FrontPage to publish pages directly to the web site. For more information about configuring FrontPage support, refer to Configuring FrontPage on page Configuring the Search Engine Zeus Web Server provides a fast and efficient search engine enabling users to search your web site for pages containing specified words. The search engine produces pages of results in response to these queries, with links to the matching files ranked in order of relevance. The search facility can be integrated easily into the pages on your web site, and its appearance can be customized. Configuring Add-Ons 267

270 Configuring the Search Engine Functionality The search engine generates an index of your web site, and uses this to produce search results. It is customizable, enabling you to change the appearance of the search page and the results pages. To configure a simple search facility on a Virtual Server 75, do the following: 1) Access the search engine page by clicking the Search Engine link in the configuration page menu. 2) Enable the search engine by clicking the appropriate radio button. 3) Enter the Search Engine Location. This is a directory, relative to the document root, that users access to perform a search. The default value of this field is /search, meaning that the search page on your web site is accessed from the URL 4) Enter the full path and name of the Index File that you want the search engine to generate. This file can be located anywhere on the machine that is running the Virtual Server; it does not need to be in the Virtual Server s document root. 5) The Search Page Template File field contains the full path and file name of the template file which controls the appearance of the search page. To use the default template file, leave this field as it is. For information on customizing the appearance of the search page, see Customizing the Appearance of the Search Engine on page ) The Results Page Template File field contains the full path and file name of the template file which controls the appearance of the search results pages. To use the default template file, leave this field as it is. For information on customizing the appearance of the search results pages, see Customizing the Appearance of the Search Engine on page ) Click the Apply changes button. When you enable the search engine, the Virtual Server s CGI support is also enabled automatically. You will be warned if you attempt to disable it. 75.The search engine functionality can be used to search a Virtual Server s web site, but cannot be used for individual Subserver web sites. 268 Configuring Add-Ons

271 Ensure that you commit the configuration for the changes to take effect, then create the search index file as described in the next section. Generating the Search Index File The search engine reads all the files on your web site and creates an index file of all the words contained in them. This file is used to answer search requests, and so must be created before the search engine will function. To create the search index file, run the searchindex program located in $ZEUSHOME/web/bin, as follows:./searchindex virtual-server-name This searches all the text and HTML files in the Virtual Server s document root, and creates the search index file in the location that you specified when configuring the search engine. i Note: You can only run the searchindex program in this way for a running Virtual Server. To create the search index file for a Virtual Server that is not running, use the searchindex program as follows:./searchindex - < configuration-file Where configuration-file is the full path and name of the Virtual Server s configuration file. This is located in the directory $ZEUSHOME/webadmin/conf/virtual_servers/sites, and has the same name as the Virtual Server. For more detailed information about using searchindex, refer to its man page. Accessing the Search Page To access the search page, enter a URL in your browser composed of your Virtual Server s host name plus the Search Engine Location you specified when configuring the search engine. For example, if the host name is and the Search Engine Location is /search, then access the search page from the URL Configuring Add-Ons 269

272 Updating the Search Index File If you change any of your web site content, the search index file will be inconsistent with the pages on your web site. To update the search index file to reflect these changes, run the searchindex program again, using the same syntax that you used before. If your web site content changes frequently, you are recommended to configure a Unix crontab entry to update the search index file on a regular basis. Excluding Files from the Search By default, the searchindex program generates a search index file from all the files in your document root that have the MIME type text/plain or text/html. If you want to exclude certain files from the search index, use the searchindex program in one of the following ways: searchindex virtual-server-name regular-expression This creates a search index file for the named Virtual Server in the Virtual Server s document root, excluding all files that match the specified regular expression. For example, to create a search index of all files except those in the /private directory, use: searchindex virtual-server-name "/private/" For information on the syntax of regular expressions, see Using Regular Expressions on page 389. searchindex virtual-server-name document-root outputfile [regular-expression] This creates a search index file for the named Virtual Server in the location specified by output-file. The index file includes all files within the specified document root except those that match the regular expression. This is useful if you want to create multiple search indexes for different parts of your web site. 270 Configuring Add-Ons

273 ! Warning: Do not create a search index that contains files that are outside your Virtual Server s document root. If you do, the search results pages will report successful matches to these files, but will not be able to display links to them. Controlling how the Search Engine Treats Files When creating the search index file, all files are treated in one of the following ways: Plain text Any file that has a MIME type of text/plain is treated as a simple text file. All the words in it are indexed. HTML Any file that has a MIME type of text/html is treated as an HTML file. HTML tags within it are ignored, and all other words are indexed. To configure the searchindex program to index other file types, and control how these files are treated, use the following options in conjunction with the searchindex program: Option --plain-type=mime-type --plain-ext=file-extension Description All files of the specified MIME type are added to the index, and treated as if they were plain text. All files that have the specified extension are added to the index, and treated as if they were plain text. Configuring Add-Ons 271

274 Option --html-type=mime-type --html-ext=file-extension Description All files of the specified MIME type are added to the index, and treated as if they were HTML files. All files that have the specified extension are added to the index, and treated as if they were HTML files. To use these options, enter them before the Virtual Server name in the searchindex command, for example: searchindex --html-ext=shtml virtual-server-name Customizing the Appearance of the Search Engine The appearance of the search engine can be customized by editing its template files: The Search Page Template File is used to control the appearance of the search page. By default, this file is $ZEUSHOME/web/etc/search_form.html. The Results Page Template File is used to control the appearance of the results pages. By default, this file is $ZEUSHOME/web/etc/search_output.html. If you customize these files, you are advised to save them in a different location and configure their new locations in your Virtual Server. This is so that the files are not overwritten when you upgrade your software. The template files are simply HTML files, in which a number of additional codes can be used. These codes are replaced with data at the time the page is displayed. 272 Configuring Add-Ons

275 The Search Page Template File can contain the following codes: Use the Code... $$url...to... specify the form s action parameter. The template file must contain an HTML form to submit the search query. Use this code in the form s action parameter, as follows: <form action="$$url;" method=post> The Results Page Template File can contain the following codes: Use the Code... $$num $$query $$output $$next $$prev $$url... to... display the approximate number of search results. display the query that produced these results. display the results of the search. create a link to the next results page. create a link to the previous results page. specify the form s action parameter if you want a search facility within the results page. If so, you must include an HTML form to submit the search query. Use the $$url code in the form s action parameter, as follows: <form action="$$url;" method=post> You can include a search query form in any HTML page, without using the Search Page Template File. To do this, include the following section of HTML code in the page: <form method="get" action="url"> Query: <input type="text" name="expr" size="20"> <input type="submit" value="search"> </form> Replace URL with the Search Engine Location, configured in the Search Engine page. Configuring Add-Ons 273

276 13.3 Configuring Server-Side Imagemaps If the Virtual Server s web site uses server-side imagemaps, enable the serverside imagemaps functionality. This is useful for supporting older browsers that cannot handle client-side imagemaps. Zeus Web Server supports serverside imagemaps in the NCSA format only. i Note: Server-side imagemaps place load on the web server, but client-side ones do not Configuring FrontPage Introducing FrontPage Functionality Microsoft FrontPage enables its users to create, modify and publish web site pages by simply saving documents to the web site. Users do this by running the FrontPage client on their local machines and publishing to the web site using the FrontPage server extensions. This section describes how to install the FrontPage server extensions on a particular web site and how to configure it to support FrontPage clients. i Note: Enabling the Virtual Server s FrontPage support automatically installs the FrontPage server extensions. Do not follow the Microsoft instructions. Introducing the FrontPage Extensions The FrontPage server extensions are a set of programs that are installed on the web site that is to be published to. They enable FrontPage users to author and administer the web site. Once you have installed the FrontPage extensions on the web site then this functionality is available to any authorized FrontPage users. 274 Configuring Add-Ons

277 i Note: Zeus Web Server supports versions up to and including version 5.0 of the FrontPage extensions (FrontPage 2002). Pre-Requisites The FrontPage Server Extensions are CGI scripts that run on the web site and use require htaccess functionality. When you enable FrontPage support, the Virtual Server s CGI and htaccess file support is also enabled automatically. You will be warned if you attempt to disable them. In a similar way, FrontPage support requires the htaccess files to be named.htaccess, and will also automatically change this name in the htaccess page. Downloading and Installing the FrontPage Extensions This section describes what to do before enabling FrontPage support on a web site. You need to install the FrontPage extensions once on each machine running any FrontPage-enabled Virtual Servers 76. When you enable FrontPage support for the first time on a Virtual Server, Zeus Web Server sets up the document root appropriately so that each FrontPage web site is independent and each FrontPage user can only access their own web site. Download and install the FrontPage extensions in the following way: 1) Identify which extension file to download. The FrontPage Extension files are available from the Microsoft web site. The files are named fpversion.platform.tar.z, where version refers the version of the FrontPage client that you are supporting, and platform refers to the operating system that the Zeus Web Server is running on. 76. If you are running FrontPage chroot-ed you will need to install it multiple times on a machine, as described in Chrooting a FrontPage Installation on page 279. Configuring Add-Ons 275

278 2) Download the appropriate file, and save it in a suitable location, such as /tmp. 3) Install the extensions in FrontPage s /usr/local/ hierarchy in the following way: a) Log in to your Zeus Web Server machine as root. b) Uncompress the compressed tar file. For example: cd /usr/local/ cat /tmp/fp50.linux.tar.z uncompress tar -xvf c) Create a symlink called currentversion that links to the directory containing the current version of FrontPage. For example: cd frontpage ln -s version5.0 currentversion Note that you must install the binaries in /usr/local/frontpage, and call the link currentversion because these names are hardcoded into the Microsoft binaries. Configure support for FrontPage by clicking the FrontPage link in the configuration page menu. Enabling and Configuring FrontPage Support Enable the Virtual Server s FrontPage support by clicking the appropriate radio button 77. This enables the Virtual Server to process FrontPage requests and run its associated CGI scripts correctly. You can then configure the FrontPage environment by setting: The installation directory (if you are running FrontPage chroot-ed), as described on page 279. Additional FrontPage directives, as described on page 278. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page This also provides support for nph-cgi scripts. To use these, configure CGI functionality in the usual way, and ensure that your nph-cgi script names start with nph-. The nph-cgi script is then responsible for generating the byte stream that is returned directly to the client without any web server post-processing. 276 Configuring Add-Ons

279 If you are enabling FrontPage support on a Virtual Server that is running on a cluster then ensure you set up the document root so that it can be accessed by all the machines in the cluster. For example, you could store it using a centralized networked file system (NFS) that can be accessed by all machines in the cluster. When you enable FrontPage support on a Virtual Server for the first time, Zeus Web Server sets up its document root(s) appropriately 78 on all the machines running the web site belonging to a Virtual Server. It then returns the username (usually fpadmin) that the FrontPage user will have to enter each time they access the web site to publish pages on it, and the associated password. It then checks whether the web site s document root already contains a.htaccess file and warns you if it finds one. It then backs it up, under a different name, before installing the FrontPage.htaccess file. This means that all functionality in your original.htaccess file (such as web site access control) will be lost unless you reintegrate all its directives. For more information about.htaccess files, refer to Using htaccess Directives on page 325. You must therefore ensure that you have configured your htaccess files to be called.htaccess. For more information about configuring this file name, refer to Enabling and Configuring htaccess File Functionality on page 200. i Note: It is best to enable FrontPage support on a Virtual Server (or Subserver) with an empty document root because existing files in the web site s document root can cause problems. In particular, hidden files, such as.htaccess files can cause difficulties. Configuring the FrontPage Forms Interface This section describes how to set up the Virtual Server to use the FrontPage forms interface with the FrontPage web site. 78. It installs the FrontPage elements into the document root using the fpinst.sh script, described in The fpinst.sh Script on page 381. Configuring Add-Ons 277

280 ! Warning: Please check the Third Party products section of the Zeus support web site for updated information concerning FrontPage configuration. 1) Symlink /usr/local/frontpage/currentversion/admin into the document root. 2) Add a new MIME type to treat.exe files as CGI scripts (as described in Adding a MIME Type on page 106). 3) Set up appropriate access control to these forms (as described in Configuring Access on page 185). Disabling a FrontPage Installation You can disable a FrontPage installation in the following ways: To prevent FrontPage users from being able to upload content to their web site, simply disable FrontPage s authoring functionality. Do this by entering the appropriate FrontPage Extension Directive as described in Configuring Additional FrontPage Extension Directives on page 278. To prevent FrontPage users from being able to upload content to their web site and stop FrontPage updating and displaying page elements, such as counters, correctly, disable FrontPage functionality on the Virtual Server. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Configuring Additional FrontPage Extension Directives Zeus Web Server enables you to enter additional FrontPage Extension Directives. It then ensures that these are distributed correctly to all the machines that are running the Virtual Server. To specify these, simply go to the Extra FrontPage Extension Directives section and enter the additional FrontPage extension directives (such as smtphost) in the text box. Zeus Web Server then automatically adds these, exactly as specified, to your FrontPage extension configuration files. Refer to 278 Configuring Add-Ons

281 your FrontPage product documentation for more information about the directives. Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Moving a FrontPage Installation To move a FrontPage-enabled document root to another Virtual Server, enable the FrontPage functionality on its new (empty) document root, and then copy all the document root files over (including any starting with a. character). Ensure that you commit the configuration to this new Virtual Server for the changes to take effect, as described in Committing Configuration Changes on page 61. Chrooting a FrontPage Installation! This section describes how to chroot your FrontPage installation. It illustrates a chroot to /web, with a document root of /web/docroot. Warning: You should only consider chroot-ing your FrontPage installation if you are familiar with using system call tracers such as truss or strace, and with chroot-ing applications. 1) Move /usr/local/frontpage to /web/usr/local/frontpage. 2) Make /usr/local/frontpage a symlink to /web/usr/local/frontpage. 3) Go to the CGI configuration page (described in Configuring chroot Jails on page 223) by clicking the CGI - Sandboxing link in the configuration page menu. In the Security Configurables section set the Run CGI scripts as file owner radio button. In the Configuring chroot Jails section, set the Run CGIs chrooted radio button. Specify a jail directory of /web. Configuring Add-Ons 279

282 i 4) Use a system call tracer to find out which libraries your FrontPage binaries require. Copy or hard-link them into your chroot-ed environment. Further details can be found on the Zeus support web site. 5) Ensure that you commit the configuration for the changes to take effect, as described in Committing Configuration Changes on page 61. Note: You can configure separate chroot-ed directories for multiple FrontPageenabled Virtual Servers. Each will need separate copies of the library files and the /usr/local/frontpage directory. In order to share a chroot-ed FrontPage installation across multiple web sites, chroot it on a Subserver enabled Virtual Server 79. This enables each of the Subserver web sites to share the chroot-ed FrontPage environment Configuring PHP Introducing PHP PHP ( is a widely-used general-purpose scripting language that is often used when constructing dynamic web pages and webbased applications. Zeus Web Server ships with a precompiled PHP binary which should be sufficient for you to set up and run simple PHP web sites. The binary is built with the default PHP options for each platform, and it includes the standard set of PHP modules. If you require support for third-party PHP modules, you will need to provide your own PHP binary. See Using your own PHP handler on page 281 for more details. 79.For more information about Subservers refer to Configuring Subservers on page Configuring Add-Ons

283 Configuring PHP To configure a virtual server to use the ZWS-supplied PHP binary to handle PHP files (files with a.php extension), follow these steps: 1) Access the PHP configuration page by clicking the PHP link in the configuration page menu. 2) Enable the PHP functionality by clicking the appropriate radio button. 3) Click the Apply changes button. To test the PHP functionality, place a file named test.php in the root directory of your web site. The file should contain just the following text: <?phpinfo()?> Access this file using the URL If PHP is functioning correctly, you will see a status page summarizing your PHP installation. Configuring Concurrency and Security Settings The PHP executable is automatically configured to be a FastCGI handler for files with a.php extension. You can apply the usual FastCGI configurables to this executable. The number of instances of the binary that you would like to run can be configured - Configuring FastCGI Concurrency on page 228 gives more information on this setting. The user and group that the binary runs as can also be configured - Configuring FastCGI Security Settings on page 229 gives more information on this. Using your own PHP handler You may wish to replace the ZWS-supplied PHP handler binary with your own. For example, your web site php files may depend on a version of PHP that includes some third-party modules, or requires a more recent release of PHP than the one supplied with ZWS. Configuring Add-Ons 281

284 In this case, you should replace the file $ZEUSHOME/php/php.fcgi with your own. Refer to the file $ZEUSHOME/php/README.PHP for more information. 282 Configuring Add-Ons

285 CHAPTER 14 Using Clusters 14.1 Introduction A cluster is a group of web servers on different machines 80 that are all running the same set of Virtual Servers so that they can act together like one big web server, and be managed as a single entity. Running a web site on a cluster of machines has the following advantages over using a single more powerful machine: The cluster provides greater fault-tolerance, because if one machine fails, the others keep running, and so the web site remains available to users. A cluster of small machines can provide the same power as one large machine, but be less expensive. A cluster is more scalable, as the power of the cluster can be increased by adding a new machine. This chapter describes how to: Create a cluster of web servers. Publish a web site on a cluster. Change the configuration of a cluster. Monitor traffic on a cluster. 80. A machine in a cluster may be running more than one web server. If this is the case then the web server is listed using a machine_name:control_port format. If there is just one web server on a machine then the web server is simply listed by machine name. Using Clusters 283

286 14.2 Creating a Cluster of Web Servers A cluster consists of a number of machines, each running one or more web server components, plus an Administration Server which is used to configure the cluster. A cluster can be made up of machines running web server components on different architectures. The Administration Server can be running on one of the web server machines, or on a separate machine. To create a cluster: 1) Install the Administration Server, and optionally, the web server component, on one of the machines. 2) Install the web server component on the other machines. 3) Configure how requests for web sites are distributed throughout the cluster of web servers on different machines. These steps are described in more detail in the sections that follow. i Note: Before installing a clustered web server, ensure that you have set up all the machines in the cluster to communicate over TCP/IP in the following way: Ensure that the machine running the Administration Server can initiate TCP/IP connections with all the machines running web servers (although the web server machines do not need to be able to initiate connections to the Administration Server machine). Ensure that the Administration Server can communicate with the web server machines either by using their IP addresses or by using their associated host names. If you use host names then you must ensure that the Administration Server can map these to the IP addresses in some way (it does not have to be using DNS). This means that the machines are not restricted to being on the same subnet, and that any-to-any communication is not necessary. 284 Using Clusters

287 Installing an Administration Server. To set up a machine to administer the cluster, install the Zeus Web Server Administration Server component. This can be installed on a machine alongside the web server component, or on its own. Install the Administration Server in one of the following ways: To install the Administration Server and the web server component on the same machine (the most common setup): a) Install Zeus Web Server by running zinstall, as described in Zeus Web Server Getting Started Guide. When asked to choose an installation option, select option 1, Full install of both admin server & web server. b) When prompted, enter your license key file name. c) When prompted, specify a password for accessing the Administration Server. d) Make a note of the Administration Server s URL, as you will need it later to access the Administration Server s web-based user interface. When the installation is complete, the Administration Server and the web server component are automatically started. Alternatively, install the Administration Server on its own. Do this if you want to use multiple web servers on different machines with identical installations, and want to run the Administration Server on a separate machine. Install the Administration Server as follows: a) Install Zeus Web Server by running zinstall, as described in Zeus Web Server Getting Started Guide. When asked to choose an installation option, select option 2, Stand-alone install of admin server. b) When prompted, specify a password for accessing the Administration Server. c) The Administration Server s URL is displayed. Make a note of it, as you will need it later to access the Administration Server s web-based user interface. This completes the installation. The Administration Server is automatically started. Using Clusters 285

288 Installing Zeus Web Server across the Cluster To install just the web server component on the other machines in the cluster, do the following: 1) Install Zeus Web Server on each machine by running zinstall, as described in Zeus Web Server Getting Started Guide. When asked to choose an installation option, select option 3, Clustered install of web server. This installs just the web server component, and not the Administration Server. 2) When prompted, enter your license key file name. 3) Enter the host name and Admin Server port number of the your previously installed Administration Server. This enables the web server to communicate with it. 4) Enter the password for accessing the Administration Server. 5) You will be asked if you are running Zeus Load Balancer. If you are not, answer no. 6) Make a note of the host_name:controlport combination for each web server on each machine (returned to you during the installation process). When the installation is complete, the web server component is automatically started and added to the cluster. Checking the Cluster Configuration To check that the web servers have been successfully added to the cluster, click the Configuration link in the Web Controller menu. The cluster configuration page displays a diagram of all the web servers in the cluster. Check that the web servers you have added are displayed 80. For more details about this page, see Viewing the Cluster Configuration on page Using Clusters

289 Configuring Request Distribution within the Cluster You have now created a cluster of web servers on different machines that are running the same set of web sites. The next step is to configure how users requests for those web sites are distributed between the machines in the cluster. This is known as load balancing the cluster. There are a number of ways of load balancing, ranging from dedicated hardware products to purely software solutions, which are beyond the scope of this manual. For more information about Zeus Load Balancer, a software solution that is fully compatible with Zeus Web Server, see The most basic load balancing method, which requires no additional hardware or software, is to use the DNS to provide simple Round Robin load balancing. To do this, create a host name for your web site, and configure the DNS to resolve this host name to the IP addresses of all the machines in the cluster. When a web browser queries the DNS to find the address of your web site, the DNS returns one of the IP addresses at random, sharing the requests across the cluster on a round-robin basis. Load balancing in this way is not ideal because the DNS uses no intelligence in the way that it distributes requests. The cluster is not fault-tolerant, because the DNS will continue to deliver requests to a machine even if the machine fails. However, by using this method, a functioning cluster can be created simply and quickly, as the following example illustrates: Suppose that you have two machines with host names alpha.myhost.com and beta.myhost.com. To configure these two machines to form a cluster called perform the following steps: 1) Install the Administration Server and the web server component on machine alpha. 2) Install just the web server component on machine beta. 3) Check that both machines have joined the cluster by viewing the Cluster Configuration page. Using Clusters 287

290 4) Configure the DNS so that it resolves to the IP addresses of both machines. Do this by adding two entries for in the DNS table, one with alpha s IP address and one with beta s IP address. This creates a cluster that shares requests between the two web servers on the different machines, and that can be administered centrally from the Administration Server Publishing a Web Site on a Cluster To publish a web site on your cluster: 1) Create a Virtual Server as described in Creating a New Virtual Server on page 45. The host name that you use depends on the way in which you have set up load balancing. If you have used the DNS to configure Round Robin load balancing as described in the previous section, use the new host name that you entered into the DNS. The Virtual Server s document root can be either a directory on a file server that all cluster machines have access to, or a directory path that exists on all machines. In the second case you must ensure that all the web site content is copied onto all the machines, and that any subsequent changes to the content are also made on all the machines. 2) A Virtual Server running on a cluster attempts to bind to all the IP addresses that its host name resolves to, resulting in warning messages when the Virtual Server is started. To prevent these unnecessary warnings, do the following: a) Access the Virtual Server s advanced configuration settings page by clicking the Advanced Settings link in the configuration page menu. b) Enter %machine% in the Bind Address field. c) Click the Apply Changes button. 3) Start the new Virtual Server, as described in Starting and Stopping Virtual Servers on page 63. You can now view the Virtual Server s web site from a web browser in the usual way. 288 Using Clusters

291 14.4 Changing the Cluster Configuration Once a cluster is running, it is possible to add a new web server (on a different machine or on an existing machine) to it, or to remove one from it, without affecting the other web servers on other machines. Adding a Web Server to a Cluster To add a new web server to a cluster, simply install the web server component on a new or existing machine, as described in Installing Zeus Web Server across the Cluster on page 286. Usually you add one web server component on each machine, although it is possible to have more than one web server on the same machine. The new web server is automatically added to the cluster. If you have Virtual Servers running on your cluster, you must deploy the Virtual Server configuration files on the new web server. For information on how to do this, see Deploying Configuration Files to a New Web Server in a Cluster on page 290. Removing a Web Server from a Cluster To remove a web server from a cluster: 1) Access the cluster configuration page by clicking the Configuration link in the Web Controller menu. 2) Click the check box corresponding to the web server that you want to remove from the cluster. 3) Click the Remove selected web servers button. Zeus Web Server removes the web server component from the cluster, but does not stop it. Reconfigure your load balancing to stop user requests being sent to this web server. Using Clusters 289

292 Returning a Web Server to a Cluster If you have removed a web server from a cluster and want to reinsert it back into the cluster again, you can do this in one of the following ways: If you know the machine s name and the web server control port number, and the web server has not been added to another cluster, do the following: a) Access the cluster configuration page by clicking the Configuration link in the Web Controller menu. b) In the Adding a Web Server to the Cluster section, enter the machine name and the web server control port number. This enables the Administration Server to communicate with it. c) Click the Add machine button. If you do not know the web server s control port number, or if the web server has been part of another cluster, do the following: a) Remove it from the other cluster, if necessary. b) Run the registerwithadminserver script located in the %ZEUSHOME%/web/bin directory. c) When prompted, enter the Administration Server s host name, Admin Server port number and password. This enables the web server to send its control port number to the Administration Server automatically. Once you have added the web server to the cluster, deploy the Virtual Server configuration files to it, as described in the next section. Deploying Configuration Files to a New Web Server in a Cluster Once you have added a new web server to the cluster, the Virtual Server status page displays a yellow Running State icon next to each running Virtual Server, warning you that the configuration files have not yet been deployed to the new web server. To deploy all the necessary configuration files, do the following: 1) Access the diagnostic information page by clicking the Diagnose icon next to the all group. 290 Using Clusters

293 2) Click the Fix all errors on this page check box. 3) Click the Fix selected problems button. You must also add the new web server to your cluster load balancing mechanism. Customizing Virtual Servers for Different Web Servers You may not want to run a Virtual Server identically on every web server in a cluster. This may be because the web servers on some machines need to run with a different document root or control port number. By default, all web servers in the cluster run the same Virtual Server configuration because the Administration Server sends an identical copy of the configuration file to each web server component when it commits the configuration to a Virtual Server on it. You can, however, set up a rewrite script to automatically make web serverspecific changes to a Virtual Server s configuration file each time the file is updated. If you set up a rewrite script on a web server, each time the web server receives a copy of the Virtual Server s configuration file, it automatically runs the script, which modifies it. A rewrite script is simply a standard Unix shell script, saved on the web server that you want to make the automatic modifications on. It must be named $ZEUSHOME/web/bin/rewrite. It is run with two parameters; the name of the Virtual Server that is being updated, and the name of the configuration file to modify. The script can be configured to make different changes depending on which Virtual Server is being updated, because the Virtual Server name is passed as a parameter to the script. The script must have Unix executable permissions set, but for security reasons it should not be group or world writable. i Note: This should not be confused with the Zeus Web Server request rewrite functionality, described in Configuring Request Rewrite Scripts on page 140. Using Clusters 291

294 The following example script changes the configuration file so that the port number is always 4000: #!/bin/sh # $1 = vserver, $2 = file # Rewrites the port number to 4000 set -e sed "s/^port.*/port 4000/" < "$2" > "$2.$$" mv "$2.$$" "$2" 14.5 Monitoring Clusters Viewing the Cluster Configuration The cluster configuration page enables you to monitor the status of all the web servers on different machines in your cluster, and view the activity of each. To view this page, click the Configuration link in the Web Controller menu. The page displays a diagram of the cluster, with each web server in the cluster represented by an icon. If the icon is pale red, it indicates that the Administration Server is unable to communicate with the web server, perhaps because it has failed or has been configured incorrectly. If the status of one of the web servers changes, this is not reflected on the cluster configuration page until you refresh the page in your browser. To force the page to be updated automatically every few seconds, click the Turn auto-refresh on button. Viewing the Activity on a Specific Web Server on a Machine To monitor the activity on a web server in the cluster, click the web server s icon to view the real-time monitoring page. This displays a graph of how often various events occur within the web server running on the machine. For further information about this functionality, see Real-Time Monitoring on page Using Clusters

295 To compare traffic on the web servers in your cluster, click the Cluster Traffic Analysis link in the Web Controller menu. From here you can see a graph of traffic on each web server on each machine over the last 24 hours or one week period. For more information, refer to Using the Cluster Traffic Analysis Page on page 81. Using Clusters 293

296 294 Using Clusters Zeus Web Server 4.3 User Guide

297 CHAPTER 15 Using Zeus Perl Extensions 15.1 Introduction Perl 81 is a very popular and flexible scripting language that many people use to help them develop their web sites. The Zeus Perl Extensions provide an interface to allow specially written Perl modules to interface with Zeus Web Server. The interface provides a rich layer of interaction with HTTP requests and headers, and is designed to provide a very high level of performance, which is much faster than using Perl in CGI scripts. The interface is compatible with Apache s mod_perl 82 interface (version 1.26), and this means there are many existing modules available which are compatible and ready to use. 83 These modules can be easily migrated from an Apache server to a Zeus Web Server. This chapter is aimed at those who are familiar with using Perl modules designed for mod_perl, and who wish to make these work under Zeus Web Server. The Zeus Perl Extensions use version of Perl. Additional technical documentation can be found in the zeus.perl(1) and perlsnoop(1) manual pages. 81. See for information about the Perl language 82. See and for information about mod_perl 83. See for many modules which work with Zeus Perl Extensions. Using Zeus Perl Extensions 295

298 15.2 Getting started with Zeus Perl Extensions Installed files Zeus Perl Extensions are part of Zeus Web Server. The Zeus Web Server installation includes following files and directories: $ZEUSHOME/zperl is the top-level directory containing the Zeus Perl Extension libraries. $ZEUSHOME/web/bin/zeus.perl is the application which runs the Zeus Perl modules. It will be automatically started whenever you start a virtual server with the Perl API module enabled. $ZEUSHOME/zperl/bin/perl is the Perl executable modified to work within the confines of a Zeus installation. It relies on a number of perl modules which are installed in $ZEUSHOME/web/lib/perl and $ZEUSHOME/zperl/lib. Installation of Perl modules The usual method of compiling and installing a Perl module is to run the Makefile.PL using the local installation of Perl. This configures the Perl module to the local environment and system. Once configured and built, the module can be installed into the Perl directory structure. When using the Zeus Perl Extensions, the correct way to configure a Perl module is to use the Zeus Perl executable: $ZEUSHOME/zperl/bin/perl Makefile.PL The Zeus Perl executable understands the Zeus directory structure and web server files. Running the Makefile.PL will automatically warn about missing prerequisites, which you can download from CPAN 84, and will produce a Makefile which will install the module into $ZEUSHOME/zperl/local. 296 Using Zeus Perl Extensions

299 ! i Then run the make command to build the module using the instructions in the generated Makefile. Then test your module by running make test. Finally, run make install to install the module into the correct location. You will need appropriate permissions for this to succeed. Warning: If you run another Perl executable that might be available on your system to configure your module, then the automatically generated Makefile may not be correctly configured to install and run as a Zeus Perl extension. Note: Even if you have already installed an existing version of Perl, the configuration choices made when building the version of Perl included in the Zeus Web Server package may differ from those on your system. This may make existing modules incompatible, requiring a rebuild against the Zeus Perl distribution in order to make them work. As a result, we recommend using CPAN as a quick means of acquiring your modules again. If you find that there are no compatibility problems then you can copy them across or install symbolic links Configuring Zeus Perl Extensions You can configure Zeus Perl Extensions by using the Zeus Administration Server interface, or by using.htaccess text files. If you are migrating a CGI module, then it is easiest to use the browser interface. However, if you are reading instructions for installing a module with Apache s mod_perl, then using text-based.htaccess files will be very similar to the installation described. You will need to enable htaccess functionality to use.htaccess files for configuration. Enable the Virtual Server s Perl Extensions support by clicking the appropriate radio button, on the Perl configuration page listed under API Support in the left-hand menu bar. To configure a new Perl Extension, add a new directory in 84. See You can also access CPAN by using the following command: $ZEUSHOME/zperl/bin/perl -MCPAN -e shell Using Zeus Perl Extensions 297

300 the space given under Add a new URL prefix, and apply the changes. This expands the section and allows you to configure additional parameters. Every Perl Extension that you configure should have at least one handler that will be called. The handler you specify should be the name of a module or a function name, and will be called when the stage of request processing matches the one you specify, for a URL request that matches the path prefix. Handlers can perform many useful tasks, including altering HTTP headers, performing authorization, generating content and logging additional information about requests. Multiple handlers can be specified, by listing them, space separated, in the handler box provided. The handler stages are listed below in the order that they are called when a request for a URL is received: Stages in order of calling Post Read Request URI Translation Header Parser Access Control Description This is called immediately after the incoming request headers have been read. Modules can perform header rewriting operations at this stage or simply use it for once-per-request operations. This is called just before translation of the incoming URL into a filename. Perl modules may wish to use the URL to install extra handlers at this stage, or to manipulate the URL and the request method. This is called just after the requested URL has been mapped into a physical filename and local.htaccess files have been read. This is called when performing access control. You should use the next stage to perform authentication; this stage is for checking the client's IP address or user-agent string. 298 Using Zeus Perl Extensions

301 Stages in order of calling Authentication Authorization MIME type checker Fixup Content Generation Logging Cleanup Description This is called when performing authentication. Modules could check passwords sent using HTTP Basic Authentication against a database entry. This stage should only be used to check if a user is valid, not whether the user is allowed to access the requested URL, which should be done in the next stage. This is called when determining whether the remote user is authorized to access the requested URL. For example, even if a user has authenticated correctly, they may also need to be a member of a particular group. This is called when assigning a MIME type (or content-type ) to the requested URL. This is called just before content generation, this stage can be used to make last-minute changes to the request. This is called when content should be generated. Modules should send content data back to the client by using methods like print(), or by printing to the STDOUT filehandle. This is called when the request is finished (whether successfully or not). It can record information about the request into a file or a database. This is called at the very end of a request, and can deallocate resources that were allocated in the process of handling the request. You may wish to define specific Environment Variables and Perl Configuration Variables which your Perl module will be able to read when it is executing. These can be specified in the relevant sections. Perl Configuration Variables are the equivalent of using PerlSetVar in a.htaccess file. Using Zeus Perl Extensions 299

302 Enabling #perl in SSI This option allows you to configure whether you can call Perl functions from within a document that uses Server Side Includes (SSI). If this is enabled, then an additional SSI tag is now valid, <!--#perl -->, which can be used within documents being served. The example below shows the use of this tag within a document: <!--#perl sub="acme" arg="foo" arg="bar" --> The #perl tag takes a number of arguments; the sub argument names a subroutine or module to invoke; if this is a module, the 'handler' subroutine in that module is used. Additional arguments foo and bar are passed to the Acme::handler function, and the output will be placed into the document at this position. Configuring additional Library Paths Modules wishing to use the Zeus Perl Extensions have to be installed into a known directory. By default, the directory $ZEUSHOME/zperl/local is searched for Perl modules. You should enter a colon separated path here of additional directories to be searched when loading modules. The directories specified will also be added to Perl variable. Configuring the Logging Level This option allows you to configure the minimum level of log message which will be logged to the Virtual Server s error log. Errors should be logged from Perl modules by using the Zeus::ModPerl::Log methods. This is equivalent to the Apache Logging level using Apache::Log Migrating existing Perl modules The Zeus Perl Extensions have been designed to make migration of existing Perl modules as easy as possible. The majority of the htaccess directives supported by Apache s mod_perl are supported, and most existing Perl modules can be migrated easily. All of the Apache::<func> functions are 300 Using Zeus Perl Extensions

303 supported, and are also available with the same arguments as Zeus::ModPerl::<func> functions. htaccess directives The instructions for some Apache mod_perl applications may ask you to put directives in httpd.conf file. When using Zeus Perl Extensions, these should be put into a global.htaccess file, a per-directory.htaccess file, or by configuring Perl Extensions using the Zeus Administration Server. Apache compatible Perl htaccess directives are described in detail in Perl directives on page 365 and Perl Handler Directives on page 366. The Perl Startup File The Zeus Perl Extensions are implemented using a parent/child process architecture. The parent process starts up when you first start a Virtual Server that uses the Zeus Perl Extensions. Child processes are periodically created and destroyed depending on the levels of requests being serviced. Initialization of Perl modules can be performed in the parent process, and this can be duplicated when a child is created without additional computation. It is efficient therefore, for modules to initialize in parent process, and this can be done by using the Perl Startup file. The Perl Startup file is run when the Perl Extensions parent process starts up. It can be used to perform configuration which affects all child runners (the processes which actually do the work of serving Perl requests) with minimal overhead. For example, if some complicated module that takes a long time to load is needed, loading it in the startup file means that it is automatically present in all child processes without the need to load it in each one individually. The startup file is kept in $ZEUSHOME/web/perlstartup.pl (this can be changed by a tuneable), and, as its extension suggests, it is simply a Perl script. It may use modules, set global variables, and even use the Apache / Zeus::ModPerl extension API in certain ways. The startup file is loaded using require(), so make sure that it returns a true value. The easiest way to do this is to end the file with a line saying simply '1;'. Using Zeus Perl Extensions 301

304 Here are a few example recipes for the startup file: httpd.conf PerlModule Foo PerlRequire /some/perl/foo.pl PerlSetEnv PERL5LIB /some/perl/lib/ perlstartup.pl use Foo; require /some/perl/foo.pl ; use lib /some/perl/lib/ ; It is possible to set a handler to be run whenever a child process starts up or shuts down. This can be done with the following code: use Zeus::ModPerl; Zeus::ModPerl->push_handlers( PerlChildInitHandler => sub { # insert child-init actions here }); Zeus::ModPerl->push_handlers( PerlChildExitHandler => sub { # insert child-exit actions here }); Registry scripts can also be compiled when the Zeus Perl Extensions are started. This can be done with the following code: use Zeus::ModPerl::RegistryLoader; my $loader = Zeus::ModPerl::RegistryLoader->new; $loader->handler( '/script.pl', '/my/docroot/script.pl' ); Using webctl with Zeus Perl Extensions Two methods have been added to webctl, the Zeus Web Server control tool, to support the Zeus Perl Extensions: perlstartup and perlrunner. The 'perlstartup' action looks for a master copy of the Perl startup file. If it finds one, it pushes it out to back-end web servers and restarts the Perl runners on those machines so that they read and act upon the new file. In a clustered setup, it is recommended that the master copy is kept in $ZEUSHOME/webadmin/conf/perl/startup.pl and webctl is used to keep it synchronized across all machines. The 'perlrunners' action simply restarts the Perl runners on all back-end machines. This may be useful if you have changed modules which some Perl 302 Using Zeus Perl Extensions

305 runners have already loaded, since they will not reload those modules automatically simply because they have changed on disk. An alternative is to use the Zeus::ModPerl::Reload module (also loadable as Apache::StatINC), for which see its documentation. The apache2zeus conversion utility The apache2zeus conversion utility is provided to convert Apache configuration files to the Zeus equivalent automatically. Apache configuration files are almost indefinitely extensible, and it is not possible to convert every configuration automatically. For this reason, the apache2zeus utility is a migration tool and isn't a perfect translator, and your migrated configuration will need checking before it can be used. apache2zeus will convert <Perl> sections and the Perl htaccess directives. The following directives are converted by apache2zeus: Directive PerlModule, PerlRequire, PerlScript Perl*Handler PerlSetEnv PerlSetVar Translation These are translated into path!/path!modules key These are translated into handler keys. The directive PerlInitHandler is translated to postreadrequest and PerlHandler is translated into a content handler. Added to the path!/path!env keys Added to the path!/path!var keys <Perl> sections are written out to a perlstartup.pl file in webadmin/conf/perl and will need reviewing since certain actions are not possible in this. Particularly you may not modify the server characteristics at this point, since perlstartup.pl is run by the Zeus Perl Runner after the virtual server has started up. Using Zeus Perl Extensions 303

306 These directives are understood but not translated: Directive Reason for not translating PerlDispatchHandler This is not configurable in Zeus PerlRestartHandler PerlFreshRestart PerlSendHeader PerlWarn PerlTaintCheck Zeus::ModPerl::Registry This is not configurable in Zeus Zeus does not restart in a way comparable to Apache The Zeus Perl Runner always sends headers when needed This is the tuning variable tuning!modules!perl!warnings <yes no> in web/global.cfg This is the tuning variable tuning!modules!perl!taintcheck <yes no> in web/global.cfg i The Registry is a module that pre-compiles and caches Perl CGI scripts. This reduces execution time if the script changes infrequently. To request that a given file be run through the Registry module, set its MIME type to application/x-httpd-perl. Note: You will not need to use the Registry for Perl modules written to use Apache or Zeus extensions, only for simple CGI scripts. 304 Using Zeus Perl Extensions

307 15.5 Differences from the Apache Perl API The following is a summary of known differences between the Apache Perl API and the Zeus Perl API: Apache C API not available Zeus only provides an emulation of the Apache Perl API, not the Apache C API. Applications which rely on the latter will require substantial porting work. PerlSendHeader The Zeus runner architecture always behaves as if PerlSendHeader were set to on, reformatting all headers as necessary. Configurable htaccess extensions not available Zeus currently has no mechanism to allow Perl applications to add extra commands to the htaccess configuration language. Accordingly, the Apache::ModuleConfig, Apache::CmdParms, and Apache::ExtUtils modules and a number of constants from Apache::Constants are not available either. subprocess_env() incomplete Setting environment variables using the subprocess_env() table should cause later subprocesses invoked by the web server to inherit those variables. This does not currently happen. <Perl> sections not available The installation processes of some Apache mod_perl applications rely upon adding a <Perl> section to the httpd.conf file. This is not available under Zeus. You should use the configuration facilities in the admin server, a startup file ($ZEUSHOME/web/perlstartup.pl by default), Using Zeus Perl Extensions 305

308 or.htaccess files, instead. Accordingly, various modules, such as Apache::PerlSections, are not available either. Missing methods The following methods are missing from the Apache module: get_client_block(), setup_client_block(), should_client_block() hard_timeout(), kill_timeout(), reset_timeout(), soft_timeout() internal_redirect(), internal_redirect_handler() httpd_conf(), set_etag() Some of these are inappropriate to Zeus. Other methods that are inappropriate to Zeus but harmless to call have stub implementations. 306 Using Zeus Perl Extensions

309 CHAPTER 16 Configuring Global Information 16.1 Introduction Global settings are settings that are configured in one place that apply to every Virtual Server on every web server on every machine in the Zeus Web Server system. To configure them, click the edit icon beside the Global Configuration item. As with the Virtual Server functionality, there are two parts to setting up this functionality: You can enable and disable functionality. This means that you can disable any unwanted functionality in order to maximize the performance of your system. You can configure the functionality. This configuration information is preserved when the functionality is disabled so that you only need to configure it once. This chapter describes the functionality that is available, and how to configure it, enable and disable it Global Functionality Overview You can configure the following global functionality: You can view and configure the Service Protection System settings as described in Configuring the Service Protection System on page 310. Configuring Global Information 307

310 This chapter provides more information about this functionality and how to configure it Using the Global Settings Pages The global settings pages are very similar in concept and layout to the Virtual Server configuration pages but configure global items. They have the same icons as the Virtual Server configuration pages and display them in the same way. This section describes the layout of these pages and how to use these pages to configure the global settings. Overview of the Layout of the Global Setting Pages This section describes the layout of the Global Settings pages. Status Indicators Button Bar Global Settings Menu Main Page Area Use and edit the Global Settings pages in the same way as the Virtual Server configuration pages, as described in Using the Configuration Pages on page Configuring Global Information