User manual APPLE LEOPARD - WEB TECHNOLOGIES ADMINISTRATION

Mac OS X Server Web Technologies Administration For Version 10.5 Leopard K Apple Inc. © 2007 Apple Inc. All rights reserved. The owner or authorized user of a valid copy of Mac OS X Server software might reproduce this publication for the purpose of learning to use such software. No part of this publication might be reproduced or transmitted for commercial purposes, such as selling copies of this publication or for providing paid-for support services. Every effort has been made to guarantee that the information in this manual is correct. Apple Inc., is not responsible for printing or clerical errors. Apple 1 Infinite Loop Cupertino, CA 95014-2084 408-996-1010 www.apple.com The Apple logo is a trademark of Apple Inc., registered in the U.S. and other countries. Use of the "keyboard" Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple might constitute trademark infringement and unfair competition in violation of federal and state laws. Apple, the Apple logo, ColorSync, Final Cut Pro, Mac, Macintosh, Mac OS, QuickTime, Xgrid, and Xserve are trademarks of Apple, Inc., registered in the U.S. and other countries. Finder and Safari are trademarks of Apple, Inc. Adobe and PostScript are trademarks of Adobe Systems Incorporated. UNIX is a registered trademark of The Open Group. Other company and product names mentioned herein are trademarks of their respective companies. Mention of third-party products is for informational purposes only and constitutes neither an endorsement nor a recommendation. Apple assumes no responsibility with regard to the performance or use of these products. 019-0945/2007-09-01 1 Contents Preface 9 9 9 10 10 11 12 12 13 13 15 15 15 16 16 16 17 17 17 17 17 17 18 18 18 19 19 19 20 20 20 21 About This Guide What's New in Version 10.5 What's in This Guide Using This Guide Using Onscreen Help Mac OS X Server Administration Guides Viewing PDF Guides Onscreen Printing PDF Guides Getting Documentation Updates Getting Additional Information Web Technologies Overview Web Technologies Overview Key Web Features Apache Web Server WebDAV CGI Support SSL Support Dynamic Content with Server Side Includes (SSI) Blogs and RSS Support Before You Begin Selecting a Version of Apache Configuring Your Web Server Providing Secure Transactions Setting Up Websites Hosting More Than One Website Understanding WebDAV Setting WebDAV Privileges Understanding WebDAV Security Defining Realms Understanding Multipurpose Internet Mail Extension (MIME) MIME Suffixes Web Server Responses (Content Handlers) Chapter 1 3 Chapter 2 23 23 24 24 24 25 27 28 29 29 30 30 31 31 31 32 32 33 33 35 35 37 37 38 39 39 40 42 43 45 47 48 49 49 49 50 50 51 52 52 53 53 Working with Web Service Setup Overview Turning Web Service On Setting Up Web Service Configuring General Settings Configuring MIME Types Settings Configuring Proxy Settings Configuring Modules Settings Configuring Web Services Settings Starting Web Service Managing Web Service Checking Web Service Status Viewing Web Service Logs Viewing Web Graphs Stopping Web Service Performance Tuning Setting Simultaneous Connections for the Web Server Setting Persistent Connections for the Web Server Setting a Connection Timeout Interval Creating and Managing Websites Website Setup Overview Setting Up Your Website Setting Up the Web Folder Creating a Website Setting the Default Webpage Configuring Website Apache Options Using Realms to Control Access Enabling Access and Error Logs for a Website Enabling Secure Sockets Layer (SSL) Managing Access to Sites Using Aliases Setting Up a Reverse Proxy Enabling Optional Web Services Connecting to Your Website Website Management Viewing Website Settings Changing the Web Folder for a Site Changing the Access Port for a Website Enabling a Common Gateway Interface (CGI) Script Enabling Server Side Includes (SSI) Creating Indexes for Searching Website Content Monitoring Website Activity Using a Passphrase with SSL Certificates Chapter 3 4 Contents 54 54 55 55 56 56 57 57 57 58 58 59 Chapter 4 61 61 62 62 62 63 64 64 65 65 66 66 66 66 67 67 68 68 68 69 69 69 70 70 70 71 71 72 72 72 Using WebDAV to Manage Website Content Enabling WebDAV on Websites Using WebDAV to Share Files Configuring Web Content File and Folder Permissions Managing Multiple Sites on One Server Using Aliases to Have a Site Respond to Multiple Names Websites and Multiple Network Interfaces User Content on Websites Web Service Configuration Default Content Accessing Web Content Securing Web Content on Case Insensitive File Systems Creating and Managing Wikis and Blogs Wiki Overview About Wiki Pages About Wiki Security About Wiki File and Folder Hierarchy Wiki Setup Overview Setting Up a Wiki Enabling Wiki Web Services for a Website Connecting to a Wiki Changing Wiki Settings Managing Wiki Pages Adding Document Pages Editing Document Pages Deleting Document Pages Adding a Link to a Wiki Page Inserting a Table on a Wiki Page Adding Tags to Wiki Pages Removing Tags from Wiki Pages Attaching a File to Wiki Pages Finding Tagged Wiki Pages Searching Wiki Pages Viewing or Replacing Older or Deleted Wiki Pages Restoring Deleted Wiki Pages Customizing Wiki Choosing Font Styles and Formatting Customizing Wiki Themes and Layouts Getting Help Using the Wiki Setting Up a Web Calendar Enabling Web Calendar Service for a Website Navigating the Web Calendar Contents 5 73 73 74 74 75 75 75 76 Chapter 5 77 77 77 78 78 78 79 80 83 83 84 84 84 85 85 86 86 86 87 88 88 89 90 90 91 92 92 92 92 93 93 93 94 Creating Timed Calendar Events Editing Calendar Events Deleting Web Calendar Events Using the Web Calendar with iCal Setting Up User and Group Blogs Enabling Blog Service for a Website Adding a Blog Page Setting Blog SACL Permissions for Users Configuring and Managing Webmail Webmail Overview Webmail User Services Webmail and Your Mail Server Webmail Protocols Enabling Webmail Configuring Webmail Setting Up Mailing List Web Archives Working with WebObjects and Open Source Applications Working with WebObjects Service WebObjects Overview Turning WebObjects Service On Setting Up WebObjects Service Starting WebObjects Service Checking the Status of WebObjects Service Stopping WebObjects Service Opening the Monitor Working with Apache Editing Apache Configuration Files Restoring the Default Configuration Using the apachectl Script About Apache Multicast DNS Registration Using Apache Axis Working with Tomcat Setting Tomcat as the Application Container Working with MySQL Turning MySQL Service On Setting Up MySQL Service Starting MySQL Service Checking the Status of MySQL Service Viewing MySQL Service and Admin Logs Stopping MySQL Service Upgrading MySQL Chapter 6 6 Contents 94 95 Chapter 7 99 99 99 100 100 101 101 102 102 102 102 102 103 103 103 103 103 103 103 103 104 104 104 107 107 107 108 113 Working with Ruby on Rails Managing the Deployment of Ruby on Rails Applications Managing Web Modules Apache Web Module Overview Working with Web Modules Viewing Web Modules Adding Web Modules Enabling Web Modules Changing Web Modules Deleting Web Modules Macintosh-Specific Modules mod_macbinary_apple mod_spotlight_apple mod_auth_apple mod_hfs_apple mod_digest_apple mod_auth_digest_apple mod_spnego mod_encoding mod_bonjour Open Source Modules Tomcat PHP mod_perl mod_encoding Solving Web Service Problems If Users Can't Connect to a Website on Your Server If a Web Module Is Not Working as Expected If a CGI Script Does Not Run Chapter 8 Index Contents 7 8 Contents This guide tells you how to set up and manage a web server, websites, and use open source web technologies. Mac OS X Server version 10.5 includes Web service that is comprised of multiple web technologies. Web service comes preinstalled on Apple server hardware and offers an integrated, flexible environment for establishing and managing web technologies. What's New in Version 10.5 Mac OS X Server v10.5 offers the following enhancements to Web service:  New and improved Apache 2.2  Group wikis and blogs  Easy certificate management in Server Admin  Control of conventional (forward) and back-end (reverse) proxies  Back-end proxy balancer, which allows simple deployment of Ruby on Rails or WebObject applications What's in This Guide This guide includes the following chapters:  Chapter 1, "Web Technologies Overview," highlights key concepts and provides basic information about configuring a server, setting up websites, and understanding specialized web components.  Chapter 2, "Working with Web Service," describes how to set up your web server for the first time and how to manage web settings and components.  Chapter 3, "Creating and Managing Websites," provides instructions for setting up and managing websites.  Chapter 4, "Creating and Managing Wikis and Blogs," describes how to use Server Admin to set up and manage wikis and blogs.  Chapter 5, "Configuring and Managing Webmail," tells you how to enable and use Webmail on your web server. Preface 9 About This Guide  Chapter 6, "Working with WebObjects and Open Source Applications," provides information and instructions related to WebObjects and open source components Apache, Tomcat, and MySQL.  Chapter 7, "Managing Web Modules," describes the modules included in Mac OS X Server and explains how to install, enable, and view modules.  Chapter 8, "Solving Web Service Problems," helps you address issues with web technologies and websites. In addition, the Glossary defines terms you'll encounter as you read this guide. Note: Because Apple frequently releases new versions and updates to its software, images shown in this book may be different from what you see on your screen. Using This Guide The following list contains suggestions for using this guide:  Read the guide in its entirety. Subsequent sections might build on information and recommendations discussed in prior sections.  The instructions in this guide should always be tested in a nonoperational environment before deployment. This nonoperational environment should simulate, as much as possible, the environment where the computer will be deployed. Using Onscreen Help You can get task instructions onscreen in Help Viewer while you're managing Mac OS X Server. You can view help on a server or an administrator computer. (An administrator computer is a Mac OS X computer with Mac OS X Server administration software installed on it.) To get help for an advanced configuration of Leopard Server: m Open Server Admin or Workgroup Manager and then:  Use the Help menu to search for a task you want to perform.  Choose Help > Server Admin Help or Help > Workgroup Manager to browse and search the help topics. The onscreen help contains instructions taken from Server Administration and other advanced administration guides described in "Mac OS X Server Administration Guides," next. To see the most recent server help topics: m Make sure the server or administrator computer is connected to the Internet while you're getting help. 10 Preface About This Guide Help Viewer automatically retrieves and caches the most recent server help topics from the Internet. When not connected to the Internet, Help Viewer displays cached help topics. Mac OS X Server Administration Guides Getting Started covers installation and setup for standard and workgroup configurations of Mac OS X Server. For advanced configurations, Server Administration covers planning, installation, setup, and general server administration. A suite of additional guides, listed below, covers advanced planning, setup, and management of individual services. You can get these guides in PDF format from the Mac OS X Server documentation website: www.apple.com/server/documentation This guide... Getting Started and Mac OS X Server Worksheet Command-Line Administration File Services Administration iCal Service Administration iChat Service Administration Mac OS X Security Configuration Mac OS X Server Security Configuration Mail Service Administration Network Services Administration Open Directory Administration Podcast Producer Administration Print Service Administration QuickTime Streaming and Broadcasting Administration Server Administration tells you how to: Install Mac OS X Server and set it up for the first time. Install, set up, and manage Mac OS X Server using UNIX commandline tools and configuration files. Share selected server volumes or folders among server clients using the AFP, NFS, FTP, and SMB protocols. Set up and manage iCal shared calendar service. Set up and manage iChat instant messaging service. Make Mac OS X computers (clients) more secure, as required by enterprise and government customers. Make Mac OS X Server and the computer it's installed on more secure, as required by enterprise and government customers. Set up and manage IMAP, POP, and SMTP mail services on the server. Set up, configure, and administer DHCP, DNS, VPN, NTP, IP firewall, NAT, and RADIUS services on the server. Set up and manage directory and authentication services, and configure clients to access directory services. Set up and manage Podcast Producer service to record, process, and distribute podcasts. Host shared printers and manage their associated queues and print jobs. Capture and encode QuickTime content. Set up and manage QuickTime streaming service to deliver media streams live or on demand. Perform advanced installation and setup of server software, and manage options that apply to multiple services or to the server as a whole. Preface About This Guide 11 This guide... System Imaging and Software Update Administration Upgrading and Migrating User Management Web Technologies Administration Xgrid Administration and High Performance Computing Guide Mac OS X Server Glossary tells you how to: Use NetBoot, NetInstall, and Software Update to automate the management of operating system and other software used by client computers. Use data and service settings from an earlier version of Mac OS X Server or Windows NT. Create and manage user accounts, groups, and computers. Set up managed preferences for Mac OS X clients. Set up and manage web technologies, including web, blog, webmail, wiki, MySQL, PHP, Ruby on Rails, and WebDAV. Set up and manage computational clusters of Xserve systems and Mac computers. Learn about terms used for server and storage products. Viewing PDF Guides Onscreen While reading the PDF version of a guide onscreen:  Show bookmarks to see the guide's outline, and click a bookmark to jump to the corresponding section.  Search for a word or phrase to see a list of places where it appears in the document. Click a listed place to see the page where it occurs.  Click a cross-reference to jump to the referenced section. Click a web link to visit the website in your browser. Printing PDF Guides If you want to print a guide, you can take these steps to save paper and ink:  Save ink or toner by not printing the cover page.  Save color ink on a color printer by looking in the panes of the Print dialog for an option to print in grays or black and white.  Reduce the bulk of the printed document and save paper by printing more than one page per sheet of paper. In the Print dialog, change Scale to 115% (155% for Getting Started). Then choose Layout from the untitled pop-up menu. If your printer supports two-sided (duplex) printing, select one of the Two-Sided options. Otherwise, choose 2 from the Pages per Sheet pop-up menu, and optionally choose Single Hairline from the Border menu. (If you're using Mac OS X v10.4 or earlier, the Scale setting is in the Page Setup dialog and the Layout settings are in the Print dialog.) You may want to enlarge the printed pages even if you don't print double sided, because the PDF page size is smaller than standard printer paper. In the Print dialog or Page Setup dialog, try changing Scale to 115% (155% for Getting Started, which has CDsize pages). 12 Preface About This Guide Getting Documentation Updates Periodically, Apple posts revised help pages and new editions of guides. Some revised help pages update the latest editions of the guides.  To view new onscreen help topics for a server application, make sure your server or administrator computer is connected to the Internet and click "Latest help topics" or "Staying current" in the main help page for the application.  To download the latest guides in PDF format, go to the Mac OS X Server documentation website: www.apple.com/server/documentation Getting Additional Information For more information, consult these resources:  Read Me documents--important updates and special information. Look for them on the server discs.  Mac OS X Server website (www.apple.com/server/macosx)--gateway to extensive product and technology information.  Mac OS X Server Support website (www.apple.com/support/macosxserver)--access to hundreds of articles from Apple's support organization.  Apple Discussions website (discussions.apple.com)--a way to share questions, knowledge, and advice with other administrators.  Apple Mailing Lists website (www.lists.apple.com)--subscribe to mailing lists so you can communicate with other administrators using email. Preface About This Guide 13 14 Preface About This Guide 1 Web Technologies Overview 1 This chapter helps you to become familiar with web technologies and to understand the major components before setting up your services and sites. The Web service is a complex suite of tools for the configuration and management of the Apache web server, development of websites, and the integration of an application server with a number of open-source components. It is best to familiarize yourself with the complexities of your system before proceeding. Web Technologies Overview Web technologies offer an integrated Internet server solution. Web technologies--also known as Web service in this guide--are easy to set up and manage, so you don't need to be an experienced web administrator to set up multiple websites and configure and monitor your web server. Web service is based on Apache, an open source HTTP web server. A web server responds to requests for HTML webpages stored on your site. Open source software gives you the capability to view and change the source code to make changes and improvements. This has led to Apache's widespread use, making it one of the most popular web servers on the Internet today. Web administrators can use Server Admin to administer Web service without knowing about advanced settings or configuration files. Web administrators proficient with Apache can also administer web technologies using Apache's advanced features. Because Web service in Mac OS X Server is based on Apache, you add advanced features with plug-in modules. Apache modules let you add support for Simple Object Access Protocol (SOAP), Java, and CGI languages such as Python. Key Web Features Web service consists of the following key components (web technologies), which provide a flexible and scalable server environment. 15       Apache Web Server WebDAV CGI Support SSL Support Dynamic Content with Server Side Includes (SSI) Blogs and RSS Support Apache Web Server Apache is an open source HTTP web server that administrators configure using Server Admin. Apache has a modular design, and the set of modules enabled by default is adequate for most uses. Server Admin controls a few optional modules. Experienced Apache users can add or remove modules and change the server code. For information about modules, see "Apache Web Module Overview" on page 99. Apache v1.3 is installed in earlier versions of Mac OS X Server. If you are doing a clean installation, use Apache 2. Automatic migration from Apache1 to Apache 2 is a supported feature of the Mac OS X Server v10.5. WARNING: There are possible side-effects of the Apache 1 to Apache 2 conversion script, particularly for security-related settings, which can impact the security of your upgrade. WebDAV Web-based Distributed Authoring and Versioning (WebDAV) is particularly useful for updating content on a website. Users who have WebDAV access to the server can open files, make changes or additions, and save those revisions. On Mac OS X, users can mount WebDAV volumes and access them seamlessly from the Finder. For more about using WebDAV for file sharing, see "Using WebDAV to Share Files" on page 55. CGI Support Common Gateway Interface (CGI) scripting provides a means of interaction between the server and clients. For example, CGI scripts let you place an order for a product offered on a website or submit responses to information requests. It is possible to write CGI scripts in several scripting languages, including Perl and Python. The folder /Library/WebServer/CGI-Executable is the default location for CGI scripts. 16 Chapter 1 Web Technologies Overview SSL Support Web service includes support for Secure Sockets Layer (SSL), a protocol that encrypts information being transferred between client and server. SSL works with a digital certificate that provides a certified identity for the server by establishing a secure, encrypted exchange of information. Dynamic Content with Server Side Includes (SSI) Server Side Includes (SSI) provide a method for using the same content on multiple pages in a site. They also can tell the server to run a script or insert specific data into a page. This feature makes updating content much easier, because you revise information in only one place and the SSI command displays that revised information about many pages. For more information about SSI, see "Enabling Server Side Includes (SSI)" on page 52. Blogs and RSS Support The web server provides blogs as an option for each website. The blogs comply with RSS and Atom XML standards and permit Open Directory authentication. Blog users can choose from several techniques for working with templates and style sheets. Important: To make service access control list (SACL) changes to blog service, it is necessary to use the server interface and not the web interface. For information about setting access control for blogs using SACLs, see "Setting Blog SACL Permissions for Users" on page 76. Before You Begin This section provides information you need before you set up your web server for the first time. Read this section even if you are an experienced web administrator. Some features and behaviors might be different from what you expect. Selecting a Version of Apache With a clean installation, Apache v2.2.4 will be installed. With an upgrade installation, you start with v1.3 but can move to v2.2.4 when you are ready to do so. Configuring Your Web Server You use Server Admin to set up and configure most features of your web server. If you are an experienced Apache administrator and need to work with features of the Apache web server that aren't included in Server Admin, change the relevant configuration files. However, Apple does not provide technical support for modifying Apache configuration files. If you alter a file, be sure to make a backup copy first. Then revert to the copy if you have problems. Chapter 1 Web Technologies Overview 17 Providing Secure Transactions If you want to provide secure transactions on your server, you must set up SSL protection. SSL lets you send encrypted, authenticated information across the Internet. For example, if you want to authorize credit card transactions through your website, you can use SSL to protect the information that's passed to and from your site. Important: You can't use the performance cache for a website if SSL is enabled for that site. For instructions on how to set up secure transactions, see "Enabling Secure Sockets Layer (SSL)" on page 43. Setting Up Websites Before hosting a website, you must:  Register your domain name with a domain name authority  Create a folder for your website on the server  Create a default page in the folder for users to see when they connect  Verify that DNS is properly configured if you want clients to access your website by name When you are ready to publish, or enable, your site, use Server Admin. The Sites pane, located within Web service, lets you add a new site and select a variety of settings for each site you host. For more information about using WebDAV for file sharing, see "Website Management" on page 49. Hosting More Than One Website You can host more than one website simultaneously on your web server. Depending on how you configure your sites, they might share the same domain name, IP address, or port. The unique combination of domain name, IP address, and port identifies each separate site. Your domain names must be registered with a domain name authority such as InterNIC. Otherwise, the website associated with the domain won't be visible on the Internet. (There is a fee for each extra name you register.) For more information about multiple sites, see "Managing Multiple Sites on One Server" on page 56. For more information about WebDAV, see "Understanding WebDAV" on page 19. For more information about MIME formats, see "Understanding Multipurpose Internet Mail Extension (MIME)" on page 20. 18 Chapter 1 Web Technologies Overview Understanding WebDAV If you use WebDAV to provide live authoring on your website, you must create realms and set access privileges for users. Each site you host can be divided into a number of realms, each with its own set of users and groups that have browsing or authoring privileges. Setting WebDAV Privileges The Apache process running on the server must have access to the website's files and folders. To provide this access, Mac OS X Server installs a user named www and a group named www in the server's Users & Groups List. The Apache processes that serve webpages run as the www user and as members of the www group. You must give the www group Read access to files in websites so the server can transfer the files to browsers when users connect to the sites. The Apache process runs with an effective user id and group id of www and needs access to the files and directories in the WebDAV realm and in the /var/run/davlocks/ folder. Understanding WebDAV Security In Mac OS X Server v10.5, WebDAV lets you use a web server as a file server. Clients use their browsers from multiple locations, on many types of computers, to access and share files on the server. For more information about using WebDAV for file sharing, see "Using WebDAV to Share Files" on page 55. WebDAV also lets users update files on a website while the site is running. When WebDAV is enabled, the web server must have write access to the files and folders in the site users are updating. Both features of WebDAV--providing a file server with browser access, and website updating--have significant security implications when other sites are running on the server, because individuals responsible for one site might be able to change other sites. You can avoid this problem by carefully setting access privileges for the site files using the File Sharing pane of Server Admin. Mac OS X Server uses a predefined group www, which contains the Apache processes. You must give the www group Read & Write access to files on the website. You also need to assign these files Read & Write access by the website administrator (Owner) and No Access to Everyone. For more information, see File Services Administration. Chapter 1 Web Technologies Overview 19 Defining Realms When you define a realm, which is typically a folder (or file system), the access privileges you set for the realm apply to all contents of that folder. If a new realm is defined for a folder in the existing realm, only the new realm privileges apply to that folder and its contents. For information about creating realms and setting access privileges, see "Using Realms to Control Access" on page 40. Note: When an assigned user or group possesses fewer permissions than the permissions that have been assigned to user Everyone, that user or group is deleted upon a refresh. This happens because the access assigned to Everyone preempts the access assigned to specific users or groups with fewer permissions than those possessed by Everyone. The greater permissions always take precedence. Consequently, the list of assigned users and groups with fewer permissions are not saved in the Realms pane upon refresh if their permissions are determined to be preempted by the permissions assigned to Everyone. After the refresh the names are no longer listed in the list on the right in the Realms pane. Also, for a brief period of time, user Everyone will switch its displayed name to "no-user." Understanding Multipurpose Internet Mail Extension (MIME) Multipurpose Internet Mail Extension (MIME) is an Internet standard for specifying what happens when a web browser requests a file with certain characteristics. You can choose the response you want the web server to make based on the file's suffix. Your choices depend partly on what modules you have installed on your web server. Each combination of a file suffix and its associated response is known as a MIME type mapping. MIME Suffixes A suffix describes the type of data in a file. Here are some examples:  txt for text files  cgi for Common Gateway Interface files  gif for GIF (graphics) files  php for PHP: Hypertext Preprocessor (embedded HTML scripts) used for Webmail, and so on  tiff for TIFF (graphics) files Mac OS X Server includes a default set of MIME type suffixes. This set includes all the suffixes in the mime.types file distributed with Apache, with a few additions. If a suffix you need is not listed or does not have the behavior you want, use Server Admin to add the suffix to the set or to change its behavior. 20 Chapter 1 Web Technologies Overview Note: Do not add or change MIME suffixes by editing configuration files. Web Server Responses (Content Handlers) When a file is requested, the web server handles the file using the response specified for the file's suffix. Responses, also known as content handlers, can be either an action or a MIME type. Likely responses include:  Return file as MIME type (you enter the mapping you want to return)  Send-as-is (send the file exactly as it exists)  Cgi-script (run a CGI script you designate)  Imap-file (generate an IMAP mail message)  Mac-binary (download a compressed file in MacBinary format) MIME type mappings are divided into two subfields separated by a forward slash, such as text/plain. Mac OS X Server includes a list of default MIME type mappings. You can edit these and add others using Server Admin. When you specify a MIME type as a response, the server identifies the type of data requested and sends the response you specify. For example, if the browser requests a file with the suffix "jpg," and its associated MIME type mapping is image/jpeg, the server knows it needs to send an image file and that its format is JPEG. The server doesn't need to do anything except serve the data requested. Actions are handled differently. If you've mapped an action to a suffix, your server runs a program or script, and the result is served to the requesting browser. For example, if a browser requests a file with the suffix "cgi," and its associated response is the action cgi-script, your server runs the script and returns the resulting data to the requesting browser. Chapter 1 Web Technologies Overview 21 22 Chapter 1 Web Technologies Overview 2 Working with Web Service 2 This chapter shows you how to use Server Admin to set up Web service and to manage web settings and components. Mac OS X Server combines the latest open source and standards-based Internet services in a complete, easy-to-use web hosting solution. Use Server Admin to configure Web service and set up web components depending on your organization's needs. Setup Overview Here is an overview of the basic steps for setting up Web service. Step 1: Read "Before You Begin" For issues you should consider before setting up Web service on your network, read "Before You Begin" on page 17. Step 2: Turn Web service on Before configuring, Web service must be turned on. See "Turning Web Service On" on page 24. Step 3: Configure web general settings Configure General settings to set connection settings and enable Tomcat. See "Configuring General Settings" on page 24. Step 4: Configure web MIME types Using MIME types you can set up how your web server responds when your browser requests certain file types. See "Configuring MIME Types Settings" on page 25. Step 5: Configure web proxy settings Use proxy settings to enable a proxy that sends requests to and from the web server. See "Configuring Proxy Settings" on page 27. Step 6: Configure web modules Use modules settings to select or deselect which web modules are available for the web server. See "Configuring Modules Settings" on page 28. 23 Step 7: Configure web services Use web service settings to set up common settings shared between wikis, blogs, web calendars, and web based mailing list archives for groups. See "Configuring Web Services Settings" on page 29. Step 8: Start Web service After you configure Web service, start the service to make it available. See "Starting Web Service" on page 29. Turning Web Service On Before you can configure Web settings, you must turn on web service in Server Admin. To turn Web service on: 1 Open Server Admin and connect to the server. 2 Click Settings, then click Services. 3 Select the Web checkbox. 4 Click Save. Setting Up Web Service Use Server Admin to change Web service settings. The following sections describe the tasks for configuring and starting Web service. There are five groups of settings on the Settings pane for Web service in Server Admin:  General. Set Web service connection and spare server settings.  MIME Types. Set up multipurpose internet mail extension (MIME) types and content handlers.  Proxy. Configure proxy settings for the web server.  Modules. Select which web modules are available for Web service.  Web Services. Configure settings common Web services that are hosted on any site. The following sections describe how to configure these settings, and a final section tells you how to start Web service when you finish. Configuring General Settings You use the General settings pane in web service to configure Web server connection settings, spare server settings, and to enable or disable Tomcat. For more information on web server connection settings, see "Performance Tuning" on page 32. To configure Web service General settings: 1 Open Server Admin and connect to the server. 24 Chapter 2 Working with Web Service 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Settings, then click General. 5 Enter the maximum simultaneous connections. The default setting is 1024 connections. This is the number of concurrent connections that are allowed to access your web server. 6 Enter the time in seconds for the connection timeout. The default setting is 300 seconds. This is the length of time before a connection to your web server times out. This happens when a user is viewing web pages but not interacting with the site. 7 Enter the number of minimum and maximum spare servers. Spare server settings regulate the creation of idle spare server processes. For maximum spare servers, if more than the maximum number of spare servers are idle, the server stops adding spare servers beyond the maximum limit. For minimum spare servers, if there are fewer than the minimum spare servers required, the server adds spare servers at a rate of one per second. 8 Enter the number of servers to start. This is the number of spare servers that get created at startup. 9 For your site to permit persistent connections, select the Allow Persistent Connections checkbox and configure the persistent connection settings: Set the Maximum persistent connections. The default is 500 connections. Set the Persistent connection timeout length in seconds. The default is 15 seconds. 10 Select the Enable Tomcat checkbox to turn Tomcat on. 11 Click Save. Configuring MIME Types Settings MIME is an Internet standard for specifying what happens when a web browser requests a file with specific characteristics. The MIME Types pane in Server Admin lets you set up how your web server responds when a browser requests certain file types. Content handlers are similar and also use suffixes to determine how a file is handled. The file suffix describes the type of data in the file. Each suffix and its associated response (such as text/plain and text/richtext) are known as a MIME type mapping or a content handler mapping. Chapter 2 Working with Web Service 25 The server includes the MIME type in its response to a browser to describe the information being sent. The browser can then use its list of MIME preferences to determine how to handle the information. The server's default MIME type is text/html, which specifies that a file contains HTML text. The web server is set up to handle the most common MIME types and content handlers. You can add, edit, or delete MIME type and content handler mappings. In Server Admin, these files are displayed in two lists: MIME Types and Content Handlers. You can edit items in each list and add or delete items in either list. To configure MIME Types settings: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Settings, then click MIME Types. 5 Add, delete, or edit MIME Type mappings. Click the Add (+) button to add a mapping to the MIME Types list. Enter each part of the name (separated by a slash), then double-click "new" in the Suffixes list and enter a suffix name. Use the Add (+) or Delete (­) button (next to the Suffixes list) to add or delete suffixes in the Suffixes list. Then click OK. To delete a MIME Type mapping, select it from the MIME Types list and click the Delete (­) button. To edit a MIME Type mapping, select the mapping from the MIME Types list and click the Edit (/) button. Make your changes to the mapping, then click OK. 6 Add, delete, or edit Content Handlers mappings. Click the Add (+) button to add a mapping to the Content Handlers list. Enter the name, then double-click "new" in the Suffixes list and enter a suffix name. Use the Add (+) or Delete (­) button (next to the Suffixes list) to add or delete suffixes in the Suffixes list. Then click OK. To delete a Content Handlers mapping, select it from the Content Handlers list and click the Delete (­) button. To edit a Content Handlers mapping, select the mapping from the Content Handlers list and click the Edit (/) button. Make your changes to the mapping, then click OK. Note: If you add or edit a handler that has a Common Gateway Interface (CGI) script, make sure you have enabled CGI execution for your site in the Options pane of the Sites pane. 26 Chapter 2 Working with Web Service 7 Click Save. Configuring Proxy Settings You use the Proxy settings pane in Web service to configure a forward proxy. A forward proxy is located between the web server and client browsers and passes requests for information between clients and server. The client must be configured to use the forward proxy to access other sites. A forward proxy is commonly used to provide Internet access to internal client computers that are restricted by a firewall. A forward proxy lets users verify a local server for frequently used files. A forward proxy can be used to block access to specific sites for internal clients and can improve performance. You can also use a forward proxy to speed response times and reduce network traffic. The proxy stores recently accessed files in a cache on your web server. Browsers on your network verify the cache before retrieving files from more distant servers. For additional security you should restrict access to your server by setting up this forward proxy. This is particularly true if your server hosts internal and external websites. If your web server is set up to act as a proxy, you can prevent the server from caching objectionable websites. Important: To take advantage of this feature, client computers must specify your web server as their proxy server in their browser preferences. When setting up a forward proxy, make sure you create and enable a website for the proxy. You might want to disable logging on the proxy site or configure the site to record its access log in a separate file from your other sites' access logs. The site does not need to be on port 80 but setting up web clients is easier if it is because browsers use port 80 by default. Mac OS X Server v10.5 provides forward and reverse proxy. The reverse proxy is configured in the Web service Sites pane. For information about setting up a reverse proxy, see "Setting Up a Reverse Proxy" on page 47. To configure Web service forward proxy settings: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Settings, then click Proxy. 5 Select the Enable Forward Proxy checkbox. If a forward proxy server is enabled, each site on the server can be used as the proxy. Chapter 2 Working with Web Service 27 6 Select the Control Access To Proxy checkbox to limit access and then enter the domain name that is permitted access in the "Allowed Domain" field. Generally, when limiting who can use your web server as a proxy, limit access to a specific domain. Users in that domain obtain access. 7 In the Cache Folder field, enter the pathname for the cache folder. You can also click the Browse button and browse for the folder you want to use. If you are administering a remote server, File service must be running on the remote server to use the Browse button. If you change the folder location from the default, you must select the new folder in Finder. Choose File > Get Info, and change the owner and group to www. 8 Set the disk cache target size and set an interval for emptying the cache. When the cache reaches this size, the oldest files are deleted from the cache folder. 9 To add a host to block, click the Add (+) button and enter its URL. Add the names of all hosts you want to block. You can import a list of websites by dragging the list to the list of blocked hosts. The list must be a text file with the host names separated by commas or tabs (also known as csv and tsv strings). Make sure the last entry in the file is terminated with a carriage return/line feed; otherwise, it is overlooked. 10 Click Save. Configuring Modules Settings You use the Modules settings pane in Web service to configure the web modules your server will use. The Web service in Mac OS X Server is modular. This means that administrators have more flexibility in the web technologies that are added to the service. For more information on web modules, see "Working with Web Modules" on page 99. To configure Web service modules settings: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Settings, then click Modules. 5 Select the Enable checkbox next to each module that you want the server to use. For information on how to add, change, or delete modules, see "Working with Web Modules" on page 99. 6 Click Save. 28 Chapter 2 Working with Web Service Configuring Web Services Settings You use the Web Services settings pane in Web service to configure common web server settings that are hosted on any site. Web services include wikis, blogs, web calendars, and web-based mailing list archives for groups. These services are independently enabled for each website you host. To configure Web service settings for your server: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Settings, then click Web Services. 5 In the Data Store field, enter the folder where Web service will store information. The default folder is /Library/Collaboration/. Click Choose to browse for a different folder. 6 In the Maximum attachment size field, enter the maximum attachment size for files that can be attached to the web services. The default file size is 50 MB. 7 From the Default Wiki and Blog Theme pop-up menu, choose the theme for your wiki. A theme controls the appearance of a wiki and blog. Themes determine the color, size, location, and other attributes of wiki and blog elements. Each theme is implemented using a style sheet. The default theme is used when a wiki or blog is initially created, but blog owners can change the theme. For more information, see "Customizing Wiki Themes and Layouts" on page 71. 8 Click Save. Starting Web Service You start Web service from Server Admin. When you make configuration changes to Web service and you save your changes, the web server is restarted, causing those changes to be recognized by the httpd process. To start Web service: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Start Web (below the Servers list). Chapter 2 Working with Web Service 29 The service runs until you stop it and restarts if your server is restarted. From the Command Line You can also start Web service using the serveradmin command in Terminal. For more information, see the Web service chapter of Command-Line Administration. Managing Web Service This section describes typical day-to-day tasks you might perform after you set up Web service on your server. Initial setup information appears in "Setting Up Web Service" on page 24. For more information about Website management, see "Website Management" on page 49. Checking Web Service Status Use Server Admin to check the status of Web service. To view Web service status: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 To see information such as whether the service is running, when it started, Apache Server version, the number of requests per second, and server throughput, click Overview. 5 To review access and error logs, click Logs. To choose which log to view, select the logs in the list. The corresponding log appears below. 6 To see graphs of connected users or throughput, click Graphs. Use the pop-up menus to choose which graph to view and the duration of time to graph data for. 7 To see a list of websites, click Sites. The list includes the domain name, address, port, and whether the site is enabled. From the Command Line You can also view the status of Web service by using the ps or top command in Terminal, or by looking at the log files in the /Library/Logs/wikid/ or /var/log/apache2/ folder using the cat or tail command. For more information, see the File services chapter of Command-Line Administration. 30 Chapter 2 Working with Web Service Viewing Web Service Logs Use Server Admin to view the error and access logs for Web service, if you have enabled them. Web service in Mac OS X Server uses the standard Apache log format, so you can also use a third-party log analysis tool to interpret the log data. To view logs: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Logs, then choose between an access or error log by selecting the log from the list of logs. To search for specific entries, use the Filter field in the lower right. From the Command Line You can also view Web service logs in the /Library/Logs/wikid/ or /var/log/apache2/ folder by using the cat or tail command in Terminal. For more information, see the Web service chapter of Command-Line Administration. Viewing Web Graphs Use Server Admin to view Web service graphs. To view web graphs: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 To see graphs of connected users or throughput, click Graphs. To choose which graph to view and the duration of time to graph data for, use the pop-up menus. 5 To update the data in the graphs, click the Refresh button (below the Servers list). Stopping Web Service Use Server Admin to stop Web service. This disconnects all users, so connected users may lose unsaved changes in open files. To stop Web service: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. Chapter 2 Working with Web Service 31 3 From the expanded Servers list, select Web. 4 Click Stop Web (below the Servers list). From the Command Line You can also stop Web service immediately using the serveradmin command in Terminal. For more information, see the Web services chapter of Command-Line Administration. Performance Tuning You can limit the period of time that users are connected to the server. You can also specify the number of connections to websites on the server at one time. Setting Simultaneous Connections for the Web Server You can specify the number of simultaneous connections to your web server. When the maximum number of connections is reached, new requests receive a message that the server is busy. Simultaneous connections are concurrent HTTP client connections. Browsers often request several parts of a webpage at the same time, and each request creates a connection. As a result, a high number of simultaneous connections can be reached if the site has pages with multiple elements and many users are trying to reach the server at one time. To set the maximum number of connections to your web server: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Settings, then click General. 5 Enter a number in the "Maximum simultaneous connections" field. The range for maximum simultaneous connections is 1 to 1024. The default is 500, but you can set the number higher or lower, taking into consideration the desired performance of your server. 6 Enter the time in seconds for the Connection timeout. The default is 300 seconds. This is the length of time before a connection to your web server times out. This happens when a user is viewing web pages but not interacting with the site. 7 Enter the number of minimum and maximum spare servers. The spare server settings regulate the creation of idle spare server processes. 32 Chapter 2 Working with Web Service For maximum spare servers, if more than the maximum number of spare servers are idle, the server stops adding spare servers beyond the maximum limit. For minimum spare servers, if there are fewer than the minimum spare servers required, the server adds spare servers at a rate of one per second. 8 Enter the number of servers to start. This is the number of spare servers that get created at startup. 9 Click Save. Setting Persistent Connections for the Web Server You can set up your web server to respond to multiple requests from a client computer without closing the connection each time. Repeatedly opening and closing connections isn't efficient and decreases performance. Most browsers request a persistent connection from the server, and the server keeps the connection open until the browser closes the connection. This means the browser is using a connection even when no information is being transferred. The Apache documentation refers to persistent connects as Keep-Alive connections. You can authorize more persistent connections--and avoid sending a Server Busy message to other users--by increasing the number of authorized persistent connections. Important: Persistent connections are not compatible with the performance cache. To set the number of persistent connections: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Settings, then click General. 5 Select Allow Persistent Connections if it is not selected. 6 Enter a number in the "Maximum persistent connections" field. The range for maximum persistent connections is 1 to 2048. 7 Click Save. Web service restarts when you save the changes. Setting a Connection Timeout Interval You can specify a time period after which the server can drop a connection that is inactive. Chapter 2 Working with Web Service 33 To set the connection timeout interval: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Settings, then click General. 5 In the "Persistent connection timeout" field, enter a number to specify the amount of time that can pass between requests before the session is disconnected by the web server. The range for connection timeout is 0 to 9999 seconds. 6 Click Save. 34 Chapter 2 Working with Web Service 3 Creating and Managing Websites 3 This chapter helps you create and manage websites that are hosted on your web server. With Web service configured and your web server running, you can create websites. You create and modify websites on your server with Server Admin. Creating a website establishes the framework that you use to provide web hosted content in various formats. Website Setup Overview Here is an overview of the basic steps for setting up a website. Step 1: Configure your web server The default configuration works for most web servers that host a single website, but you can configure all basic features of Web service and websites using Server Admin. For more information, see Chapter 2, "Working with Web Service." For more advanced configuration options, see Chapter 6, "Working with WebObjects and Open Source Applications." To host user websites, you must configure at least one website. Step 2: Set up the web folder When your server software is installed, a folder located at /Library/WebServer/ Documents/ is set up in the file system. Put items you want to make available through a website in the web folder. You can create subfolders in the web folder to organize the information, and it is generally recommended that you do so if you create additional virtual hosts. In addition, each registered user has a Sites folder in the user's home folder. Graphics or HTML pages stored in the user's Sites folder are served from http://server.example.com/ ~username/. For more information, see "Setting Up the Web Folder" on page 37. 35 Step 3: Assign privileges for your website The Apache processes that serve webpages must have Read access to the files and Read/Execute access to the folders. (In the case of folders, Execute access means the ability to read the names of files and folders contained in that folder.) Those Apache processes run as user www--a special user created for Apache when Mac OS X Server is installed. User www is a member of group www, so for the Apache process to access the content of the website, the files and folders must be readable by user www. You must give group www at least Read-Only access to files in your website so it can transfer those files to browsers when users connect to the site. This applies to all parent folders as well. In other words, the folder containing your web content and the folder containing that folder, and so on, must be readable and searchable by user or group www. You can do this by:  Making the files and folders readable and searchable by everyone regardless of their user or group ownership.  Making group www the owner of files and folders and making sure that the files and folders are readable and searchable by the owner.  Making group www the owner of files and folders and making sure the files and folders are readable and searchable by the group.  Making sure the files and folders are readable and searchable by everyone (world), regardless of their ownership and group settings. This is the default case. For information about assigning privileges, see File Services Administration. Step 4: Create the website Use Server Admin to create a website. After the site is created, configure the settings for your network environment and web requirements. For details, see "Creating a Website" on page 38. Step 5: Set the default page When users connect to your website, they see the default page. When you first install the software, the file index.html in the Documents folder is the default page. Replace this file with the first page of your website and name it index.html. To name the file something else, add that name to the list of default index files and move its name to the top of the list in the General pane of the site settings window of Server Admin. For instructions about specifying default index file names, see "Setting the Default Webpage" on page 39. Step 6: (Optional) Configure website Apache options Use the Sites Options pane to configure Apache web options. For details, see "Configuring Website Apache Options" on page 39. 36 Chapter 3 Creating and Managing Websites Step 7: (Optional) Creating realms to control website access You can create a realm to control access to locations or folders in a website. Use the Sites Realms pane to configure your website realms. For details, see "Using Realms to Control Access" on page 40. Step 8: Enable website access and error logs Use the Logging pane in the Sites pane to enable access and error logs for your website. For details, see "Enabling Access and Error Logs for a Website" on page 42. Step 9: (Optional) Enable SSL Use the Security pane in the Sites pane to enable SSL for your website. For details, see "Enabling Secure Sockets Layer (SSL)" on page 43. Step 10: (Optional) Creating website aliases and redirects Use the Aliases pane in the Sites pane to configure website aliases and redirects. For details, see "Managing Access to Sites Using Aliases" on page 45. Step 11: (Optional) Set up a reverse proxy Use the Proxy pane in the Sites pane to configure a reverse proxy for your website. For details, see "Setting Up a Reverse Proxy" on page 47. Step 12: (Optional) Enable optional website features Use the Web Services pane in the Sites pane to enable optional web services. For details, see "Enabling Optional Web Services" on page 48. Step 13: Connect to your website To make sure the website is working properly, open your browser and try to connect to your website over the Internet. If your site isn't working correctly, see Chapter 8, "Solving Web Service Problems," on page 107. Setting Up Your Website The following sections provide instructions for setting up your website. Setting Up the Web Folder To make files available through a website, put the files in the web folder for the site. To organize the information, you can create subfolders inside the web folder. The folder is located at /Library/WebServer/Documents/. In addition, each registered user has a Sites folder in the user's home folder. Graphics or HTML pages stored here are served from http://server.example.com/~username/. To set up the web folder for your website: 1 Open the web folder on your web server. By default, the documents folder is located at /Library/WebServer/Documents/. Chapter 3 Creating and Managing Websites 37 2 Replace the index.html file with the main page for your website. Make sure the name of your main page matches the default document name you set in the Sites General pane. For details, see "Setting the Default Webpage" on page 39. 3 Copy files you want available on your website to the web folder. Creating a Website Use Server Admin to create a website framework. This allows content from the web folder to be hosted by your web server. Before you can create a website, you must produce the content for the site and set up your site folders. To create a website: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Sites, then click the Add (+) button to add a new site. 5 In the Sites General pane, enter the fully qualified DNS name of your website in the Domain Name field. Note: You can leave the domain name blank and the IP address set to "any" and the site remains operational. 6 Enter the IP address and port number for the site. The default port number is 80. If you are using SSL, the port is 443. Make sure the number you choose is not in use by another service on the server. To enable your website on the server, the website must have a unique name, IP address, and port number combination. For more information see "Hosting More Than One Website" on page 18. WARNING: Do not try to access the server through the direct ports. Instead, allow your access to be proxied through Apache as it is set up. For instance, Server Admin provides no obvious way to configure wikis, and will return the xmlrpc error. In addition, do not access the wiki server on port 8086 or 8087. 7 Enter the path to the folder you set up for this website. You can also click the Choose button and browse for the folder you want to use. 8 In the Error Document field, enter the page you want to appear when a web page error occurs. 9 (Optional) In the Administrator Email field, enter the administrator mail address. The server sends website error messages to this mail address. 38 Chapter 3 Creating and Managing Websites 10 Click Save. Setting the Default Webpage The default page appears when a user connects to your website by specifying a folder or host name instead of a file name. You can have more than one default page (known as a default index file in Server Admin) for a website. If multiple index files are listed for a website, the web server uses the first one listed in the web folder for that website. To set the default webpage: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Sites, then select the website in the list. 5 Click General below the websites list. 6 At the right of the Default Index Files list, click the Add (+) button and enter a name (but do not use spaces in the name.) A file with this name must be in the web folder. 7 To set the file as the default page the server displays, drag that file to the top of the list. 8 Click Save. Note: If you plan to use only one index page for a site, you can leave index.html as the default index file and change the content of the existing file with that name in /Library/ WebServer/Documents/. Configuring Website Apache Options The default page appears when a user connects to your website by specifying a folder or host name instead of a file name. To configure website Apache options: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Sites, then select the website in the list. 5 Click Options below the websites list. 6 Select any of the following Apache options your website requires: Chapter 3 Creating and Managing Websites 39 Folder Listing: Displays a list of folders when users specify the URL and no default webpage (such as index.html) is present. Instead of viewing a default webpage, the server shows a list of the web folder's contents. Folder listings appear only if no default document is found. WebDAV: Turns Web-based Distributed Authoring and Versioning (WebDAV) on, which allows users to make changes to websites while the sites are running. If you enable WebDAV you must also assign access privileges for the sites and for the web folders. CGI Execution: Permits Common Gateway Interface (CGI) programs or scripts to run on your web server. CGI programs or scripts define how a web server interacts with external content-generating programs. For more information, see "Enabling a Common Gateway Interface (CGI) Script" on page 51. Server Side Includes (SSI): Permits SSI directives placed in web pages to be evaluated on the server while the website is active. You can add dynamically generated content to your web pages while the files are being viewed by users. For more information, see "Enabling Server Side Includes (SSI)" on page 52. Allow All Overrides: Instructs Web service to look for additional configuration files inside the web folder for each request. Spotlight Searching: Allows web browsers to search the content of your website. For details on configuring website indexing, see "Creating Indexes for Searching Website Content" on page 52. 7 Click Save. Using Realms to Control Access You can use realms to control access and provide security to locations or folders within a website. Realms are locations at the URL or they are files in the folder that users can view. If WebDAV is enabled, users with authoring privileges can also change content in the realm. You set up the realms and specify the users and groups that have access to them. When an assigned user or group possesses fewer permissions than the permissions that have been assigned to user Everyone, that user or group is deleted upon a refresh. This happens because the access assigned to Everyone preempts the access assigned to specific users or groups with fewer permissions than those possessed by Everyone. The greater permissions always take precedence. Consequently, the list of assigned users and groups with fewer permissions are not saved in the Realms pane upon refresh if their permissions are determined to be preempted by the permissions assigned to Everyone. After the refresh the names are no longer listed in the list on the right in the Realms pane. Also, for a brief period of time, user Everyone will switch its displayed name to "no-user." 40 Chapter 3 Creating and Managing Websites To use a realm to control website access: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Sites, then select the website in the list. 5 Click Realms below the websites list. 6 Click the Add (+) button to create a realm. The realm is the part of the website users can access. 7 In the Realm Name field, enter the realm name. This is the name users see when they log in to the website. 8 From the Authentication pop-up menu, choose a method of authentication. Basic authentication is on by default. Don't use basic authentication for sensitive data because it sends your password to the server unencrypted. Digest authentication is more secure than basic authentication because it uses an encrypted hash of your password. Kerberos authentication is the most secure because it implements server certificates to authenticate. If you want Kerberos authentication for the realm, you must join the server to a Kerberos domain. 9 Enter the realm location or folder you are restricting access to: Choose Location from the pop-up menu and enter a URL to the location in the website that you want to restrict access to. Choose Folder from the pop-up menu and enter the path to the folder that you want to restrict access to. You can also click the Browse button to locate the folder you want to use. 10 Click OK. 11 Select the new realm and click Add (+) to open the Users & Groups panel. To switch between the Users list and the Groups list, click Users or Groups in the panel. 12 To add users or groups to a realm, drag users to the list on the right in the Realms pane. When users or members of a group you've added to the realm connect to the site, they must supply their user name and password. 13 Limit realm access to specified users and groups by setting the following permissions using the up and down arrows in the Persmissions column. Browse Only: Permits users or groups to browse the website. Chapter 3 Creating and Managing Websites 41 Browse and Read WebDAV: Permits users or groups to browse the website and also read the website files using WebDAV. Browse and Read/Write WebDAV: Permits users or groups to browse the website and also read and write to website files using WebDAV. None: Prevents users or groups from using any permissions. 14 Click Save. Use the Realms pane to delete a user or group by selecting the name and clicking the Delete (­) button. Enabling Access and Error Logs for a Website When enabled, Web service keeps access and error logs for your website. You can set up error and access logs for individual websites that you host on your server. However, enabling logs can slow server performance. The access log contains an entry for each access to the website, indicating what page was accessed, by whom, and whether the access was successful, along with other details. The error log contains information about failed accesses, or various conditions of interest to the administrator. This log prioritizes messages using severity levels ranging from debug to critical. Server Admin can limit the messages logged by the level of severity. By default, messages are logged at a "warning" level threshold. In addition to per-site logs, there is an access log and an error log for the wikid process, which provides logging for wikis. Finally, if you upgraded to Mac OS X Server v10.5 from Mac OS X Server v10.3 or Mac OS X Server v10.4, and the Apache Mode was changed from Apache 1 to Apache 2, there will be a Web Service migration log, which details the actions taken by the Apache 1.3 -> 2.2 translation script. To enable access and error logs for a website: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Sites, then select the website in the list. 5 Click Logging below the websites list. 6 Select Enable Access Log to enable this log. 7 Set how often you want the Access log to be archived by selecting the "Archive every __ days" checkbox and entering the number of days. 42 Chapter 3 Creating and Managing Websites 8 In the Location field, enter the path to the folder where you want to store access logs. If you are working with multiple websites, you can name separate logs for each website. You might want to include the site domain name in the log name for easy recognition when reviewing logs. If you have only two websites, you might want to use a single log (with the default name the server uses). You can also click the Browse button to locate the folder you want to use. If you are administering a remote server, File service must be running on the remote server to use the Browse button. 9 From the Format pop-up menu, choose a log format. 10 If necessary, edit the format string. Note: The Help button next to the format string opens the Apache documentation web page (http://httpd.apache.org/docs/mod/mod_log_config.html), which explains parameters for format strings. 11 Set how often you want the Error log to be archived by selecting the "Archive every __ days" checkbox for the Error log and entering the number of days. 12 In the Error log Location field, enter the path to the folder where you want to store error logs. You can also click the Browse button to locate the folder you want to use. 13 Choose the level of error in the Level pop-up menu to set which error message priority gets logged. 14 Click Save. Enabling Secure Sockets Layer (SSL) Secure Sockets Layer (SSL) provides security for a site and its users by authenticating the server, encrypting information, and maintaining message integrity. SSL is a per-site setting that lets you send encrypted, authenticated information across the Internet. For example, if you want to permit credit card transactions through a website, you can protect the information that's passed to and from that site. The SSL layer is below application protocols (for example, HTTP) and above TCP/IP. This means that when SSL is operating on the server and on the client computer, all information is encrypted before being sent. The Apache web server in Mac OS X Server uses a public key-private key combination to protect information. A browser encrypts information using a public key provided by the server. Only the server has a private key that can decrypt that information. The web server supports SSLv2, SSLv3, and TLSv1. More information about these protocol versions is available at www.modssl.org. Chapter 3 Creating and Managing Websites 43 When SSL is implemented on a server, a browser connects to it using the https prefix in the URL, rather than http. The "s" indicates that the server is secure. When a browser initiates a connection to an SSL-protected server, it connects to a specific port (443) and sends a message that describes the encryption ciphers it recognizes. The server responds with its strongest cipher, and the browser and server then continue exchanging messages until the server determines the strongest cipher that it and the browser can recognize. The server then sends its certificate (an ISO X.509 certificate) to the browser. This certificate identifies the server and uses it to create an encryption key for the browser to use. At this point a secure connection has been established and the browser and server can exchange encrypted information. Before you can enable SSL protection for a website, you must obtain the proper certificates. For detailed information about certificates and their management, see Server Administration. To set up SSL for a website: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Sites, then select the website in the list. 5 Click Security below the websites list. 6 In the Security pane, select Enable Secure Sockets Layer (SSL). When you turn on SSL, a message appears, noting that the port is changed to 443. 7 In the Certificate pop-up menu, choose the certificate you want. If the certificate is protected by a passphrase, the name of the certificate must match the virtual host name. If the names don't match, Web service won't restart. 8 If you choose Custom Configuration or want to edit a certificate, you might have to do the following: a Click the Edit (/) button and supply the correct information in each field for the certificate. b If you received a ca.crt file from the certificate authority, click the Edit (/) button and paste the text from the ca.crt file in the Certificate Authority File field. Note: The ca.crt file might be required but might not be sent directly to you. This file must be available on the website of the certificate authority. c In the Private Key Passphrase field, enter a passphrase and click OK. 9 Click Save. 44 Chapter 3 Creating and Managing Websites 10 Confirm that you want to restart Web service. Server Admin lets you enable SSL with or without saving the SSL passphrase. If you did not save the passphrase with the SSL certificate data, the server prompts you for the passphrase upon restart but won't accept manually entered passphrases. Use the Security pane for the site in Server Admin to save the passphrase with the SSL certificate data. For more information, see "Using a Passphrase with SSL Certificates" on page 53. Managing Access to Sites Using Aliases You can manage access to websites by using aliases and redirect commands. An alias is an alternative name for a website, which can be useful in simplifying the name users must enter to connect to the site. You can have multiple aliases for a single site. For example, with a host named example.com you might want to provide a server alias named www.example.com. The Server Admin Sites Aliases panel mixes two types of aliases.  The top half of the panel is for web server aliases that give an alternate name to the website or virtual host.  The bottom half of the panel is for URL aliases and redirects, which are more finegrained. By default, the Sites Aliases panel lists a Web Server Alias * (wildcard) directive. To perform name-based virtual hosting, remove the wildcard. If you do not remove the wildcard, browsers trying to access your virtual hosts will access the default host instead. Note: Server aliases and virtual hosts must be DNS names and they must resolve to the IP address of the website. A redirect command specifies that when users ask for a specific folder or file on a site, their browser is sent to a different location that you designate. For example, you could set up a redirect so that if the user enters a URL such as www.example.com/images/boats.jpg and the site has an images folder containing the boats.jpg file, the browser gets redirected to www.apple.com. By default, the Sites Aliases panel lists the following redirects:  /collaboration - used to provide the CSS required by Apple's wiki and blog pages and default index.html and Spotlight displays  /icons/ - used to direct browsers to the standard collection of icons shipped with Apache  /error/ - used to direct browsers to the standard collection of error pages shipped with Apache Chapter 3 Creating and Managing Websites 45 The examples below show aliases and redirects. Type Alias Pattern /images Path /Volumes/Data/imgs Description If you make a file system change but don't want to update all image URLs in your HTML files, this instructs www.example.com/images/boat.jpg to take the file from /Volumes/Data/imgs/ boat.jpg. If you store all gifs in a specific folder but they must be referenced from the web server root, this instructs the alias www.example.com/logo.gif to serve the file located at /Library/WebServer/ Documents/gifs/logo.gif. Alias Match ^/(.*)\.gif /Library/WebServer/ Documents/ gifs$1.jpg Redirect /webstore https:// This redirects all queries for webstore to secure.example.com/ the secure server. webstore http:// If you host static content such as imageserver.example. images on a new server, this redirects com$1.jpg all requests for files ending in .jpg to a different server. Redirect Match (.*)\.jpg Further information and other examples of aliases and redirects are available at http:// httpd.apache.org/docs/mod/mod_alias.html. To create or edit aliases the site responds to: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Sites, then select the website in the list. 5 Click Aliases below the websites list. 6 To create aliases, click the Add (+) button under the Web Server Aliases list or select an alias and click the Edit button. 7 In the Server Alias field, enter an alias and click OK. 8 To create a redirect, click the Add (+) button under URL Aliases and Redirects list or select a redirect and click the Edit (/) button. 9 Choose one of the following options from the Type pop-up menu. Alias: Maps from the URL term to a location in the file system. Alias Match: Maps a regular expression pattern for a path to a location in the file system. 46 Chapter 3 Creating and Managing Websites Redirect: Maps a URL term to redirect to another server. Redirect Match: Maps a regular expression pattern for a path to redirect to another server. 10 In the Pattern field, enter the pattern for the alias or redirect. This is the pattern input from the incoming URL. 11 In the Path field, enter the path for the alias or redirect and click OK. This is the path in the file system or the redirect that gets sent back to the requester. 12 Click Save. Setting Up a Reverse Proxy You set up a reverse proxy using the Proxy pane in the Sites pane of Server Admin. A reverse proxy differs from a forward proxy by appearing to client computers as a normal web server. The client computers make requests to the web server. The reverse proxy then determines the location to send the requests to and returns web content as if it were the web server. Client computers do not need configuration changes to use a reverse proxy. You can use a reverse proxy to provide Internet users access to a server located behind a firewall. A reverse proxy can also balance network traffic among several back-end servers or provide caching for a slower back-end server. Administrators also use a reverse proxy to bring several servers into the same URL space. Mac OS X Server v10.5 provides both forward and reverse proxy. The forward proxy is configured in the Web service Settings pane. For information about setting up a forward proxy, see "Configuring Proxy Settings" on page 27. To enable reverse proxy: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Sites, then select the website in the list. 5 Click Proxy below the websites list. 6 Select the Enable Reverse Proxy checkbox. 7 In the Proxy Path field, enter the proxy pathname. 8 In the Sticky Session Identifier field, enter a sticky session identifier or choose one from the pop-up menu. Chapter 3 Creating and Managing Websites 47 A sticky session identifier is used to bind a user that is browsing your site to the server that the session started on. This keeps users that are browsing a website that is supported by multiple web servers connected to the server that they started with. 9 To add balancer members, click the Add (+) button below the Balancer Members list; enter a Server URL (worker URL) and define its route and load factor, then click OK. A balancer member is a server (designated by its worker URL) that shares the network traffic generated by website sessions. Multiple balancers share the website traffic by binding and routing a predetermined load to each server. This prevents a single server from being inundated by web traffic and it improves performance. The route of the worker URL is a value appended to the sticky session ID. The load factor is a number between 1 and 100 that defines how much load the worker will handle. 10 Add additional balancer members as necessary, depending on your network requirements. 11 Click Save. Enabling Optional Web Services You can enable additional web services such as wikis, blogs, or webmail. To enable optional web services: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Sites, then select the website in the list. 5 Click Web Services below the websites list. 6 Select the Webmail checkbox to enable webmail for your website. Webmail adds mail functionality for each user of your website. For more information about setting up Webmail, see "Configuring Webmail" on page 79. 7 Select the Blog checkbox to enable blogs for your website. A blog is a chronological journal on your website that is updated with content added by users. For more information, see "Setting Up User and Group Blogs" on page 75. 8 Select the Wiki and blog checkbox to enable group website functionality. This website functionality makes it easy for groups to create and distribute information in their own shared websites. For details, see "Setting Up a Wiki" on page 64. 9 Select the Web calendar checkbox if you want calendar functionality for your website. Users can access a group calendar to track meetings and deadlines. 48 Chapter 3 Creating and Managing Websites For details, see "Setting Up a Web Calendar" on page 72. 10 Select the Mailing list web archive checkbox if you want mailing list functionality on your website. A mailing list is a discussion group that uses mass mail to facilitate communication. For details, see "Setting Up Mailing List Web Archives" on page 80. 11 Click the Add (+) button below the Users/Group list to add users and groups that will create wikis on your site. Select the Moderator checkbox for each user or group that you want to designate as a moderator. If the list is empty, all users can create wikis. 12 Click Save. Connecting to Your Website After you configure your website, view the site with a web browser to verify that everything appears as intended. To connect to your website: 1 Open a web browser and enter the web address of your server. You can use the IP address or the DNS name of the server. If SSL is enabled, use "https" in the URL instead of "http." 2 If you are not using the default port, enter the port number. 3 If you've restricted access to specific users, enter a valid user name and password. WARNING: Do not try to access the server through the direct ports. Instead, allow your access to be proxied through Apache as it is set up. For instance, Server Admin provides no obvious way to configure wikis and will return the xmlrpc error. Do not access the wiki server on port 8086 or 8087. 4 Verify that the website default index page appears. Website Management This section describes typical tasks you might perform after you create a website on your server. Initial website setup information appears in "Setting Up Your Website" on page 37. Viewing Website Settings You can use the Sites pane of Server Admin to see a list of your websites. The Sites pane lists configuration information for each site, including:  Whether a site is enabled Chapter 3 Creating and Managing Websites 49  The DNS name and IP address for a site  The port being used for the site To view website settings: 1 Open Server Admin and connect to the server. 2 Click the triangle to the left of the server. The list of services appears. 3 From the expanded Servers list, select Web. 4 Click Sites, then select the website in the list. You can view or change the settings for a site by selecting the site in the Sites pane list and clicking a setting pane. Changing the Web Folder for a Site The web folder is used as the root for the site (known as DocumentRoot in Apache). In other words, the default folder is the top level of the file system structure for the site. To change the web folder for a site hosted on your server: 1 Log in to the server you want to administer. You need access to the file system on the server. 2 Drag the contents of your previous web folder to your new web folder. 3 Open Server Admin and connect to the server. 4 Click the triangle to the left of the server. The list of services appears. 5 From the expanded Servers list, select Web. 6 Click Sites, then select the website in the list. 7 In the website General pane, enter the path to the web folder in the Web Folder field, or click the Browse button and navigate to the new web folder location. 8 Click Save. Changing the Access Port for a Website By default, the server uses port 80 for connections to websites on your server. You might need to change the port used for an individual website (for example, if you want to set up a streaming server on port 80). Make sure the number you choose does not conflict with ports being used on the server (for FTP, Apple File Service, SMTP, and others). If you change the port number for a website you must change all URLs that point to the web server to include the new port number you choose. 50 Chapter 3 Creating and Managing Websites