034-2350_Cvr 9/12/03 7:31 AM Page 1 Mac OS X Server Web Technologies Administration For Version 10.
LL2350.book Page 2 Friday, August 22, 2003 2:32 PM Apple Computer, Inc. © 2003 Apple Computer, Inc. All rights reserved. The owner or authorized user of a valid copy of Mac OS X Server software may reproduce this publication for the purpose of learning to use such software. No part of this publication may be reproduced or transmitted for commercial purposes, such as selling copies of this publication or for providing paid for support services.
LL2350.
LL2350.
LL2350.
LL2350.
LL2350.book Page 7 Friday, August 22, 2003 2:32 PM 1 Web Technologies Overview 1 Become familiar with web technologies and understand the major components before setting up your services and sites. Web technologies in Mac OS X Server offer an integrated Internet server solution. Web technologies—also called 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.
LL2350.book Page 8 Friday, August 22, 2003 2:32 PM Key Web Components Web technologies in Mac OS X Server consist of several key components, which provide a flexible and scalable server environment. Apache Web Server Apache is an open-source HTTP web server that administrators can configure with the Server Admin application. Apache has a modular design, and the set of modules enabled by default is adequate for most uses. Server Admin can control a few optional modules.
LL2350.book Page 9 Friday, August 22, 2003 2:32 PM Front-End Cache The web server includes a high-performance cache that increases performance for websites that serve static pages. The static content stays in the cache once used, so the server can quickly retrieve this content when it is requested again. Before You Begin This section provides information you need to know before you set up your web server for the first time.
LL2350.book Page 10 Friday, August 22, 2003 2:32 PM 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 may 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.
LL2350.book Page 11 Friday, August 22, 2003 2:32 PM You can avoid this problem by carefully setting access privileges for the site files using the Sharing module of the Workgroup Manager application. Mac OS X Server uses a predefined group www, which contains the Apache processes. You need to give the www group Read & Write access to files within the website. You also need to assign these files Read & Write access by the website administrator (Owner) and No Access to Everyone.
LL2350.book Page 12 Friday, August 22, 2003 2:32 PM 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. When you specify a MIME type as a response, the server identifies the type of data requested and sends the response you specify.
LL2350.book Page 13 Friday, August 22, 2003 2:32 PM 2 Managing Web Technologies 2 Use Server Admin to set up web technologies initially and to manage web settings and components. If you are familiar with web servers and their content, you can use these summary steps to get your web server started. If you’d like more detailed instructions for these tasks, see the similar topics in “Using Server Admin to Manage Your Web Server” on page 15 and Chapter 3, “Managing Websites,” on page 23.
LL2350.book Page 14 Friday, August 22, 2003 2:32 PM 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 particular folder.) Those apache processes run as user www—a special user created specifically for Apache when Mac OS X Server is installed. The user www is a member of the group www.
LL2350.book Page 15 Friday, August 22, 2003 2:32 PM Step 5: Start web service 1 Open Server Admin and click Web in the list below the server name. 2 Click Start Service in the toolbar. Important: Always use Server Admin to start and stop the web server. You can start the web server from the command line, but Server Admin won’t show the change in status for several seconds. Server Admin is the preferred method to start and stop the web server and modify web server settings.
LL2350.book Page 16 Friday, August 22, 2003 2:32 PM Starting Web Service Automatically Web service is set to start automatically (if it was running at shutdown) when the server starts up. This will ensure that your websites are available if there’s been a power failure or the server shuts down for any reason. When you start web service in the Server Admin toolbar, the service starts automatically each time the server restarts.
LL2350.book Page 17 Friday, August 22, 2003 2:32 PM 4 In the new sheet that appears, do one of the following: • For a new MIME type, type each part of the name (separated by a slash), select the suffix and type its name, use the Add button to add any suffixes you want, then click OK. • For a new content handler, type a name for the handler, select the suffix and type its name, use the Add button to add any suffixes you want, then click OK.
LL2350.book Page 18 Friday, August 22, 2003 2:32 PM 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 very 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.
LL2350.book Page 19 Friday, August 22, 2003 2:32 PM Setting Up Proxy Caching A proxy lets users check a local server for frequently used files. You can use a proxy to speed up response times and reduce network traffic. The proxy stores recently accessed files in a cache on your web server. Browsers on your network check the cache before retrieving files from more distant servers.
LL2350.book Page 20 Friday, August 22, 2003 2:32 PM Blocking Websites From Your Web Server Cache 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. You can import a list of websites by dragging it to list of sites.
LL2350.book Page 21 Friday, August 22, 2003 2:32 PM The Apache 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. 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.
LL2350.book Page 22 Friday, August 22, 2003 2:32 PM Viewing Web Service Status In Server Admin you can check the current state of the Apache server and which server modules are active. Web Service Overview The overview in Server Admin shows server activity in summary form. To view web service status overview: 1 Open Server Admin. 2 Click Overview in the button bar. The Start/Stop Status Messages field displays a summary of server activity and the server’s start date and time.
LL2350.book Page 23 Friday, August 22, 2003 2:32 PM Managing Websites 3 3 Use the Server Admin application to set up and manage the essential components of web service. You administer websites on your server with Server Admin, an application that allows you to establish settings, specify folders and paths, enable a variety of options, and view the status of sites.
LL2350.book Page 24 Friday, August 22, 2003 2:32 PM To set up the Documents folder for your website: 1 Open the Documents folder on your web server. If you have not changed the location of the Documents folder, it’s in this directory: /Library/WebServer/Documents/. 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 General pane of the site’s Settings window.
LL2350.book Page 25 Friday, August 22, 2003 2:32 PM Changing the Default Web Folder for a Site A site’s default web folder is used as the root for the site. In other words, the default folder is the top level of the directory structure for the site. To change the default web folder for a site hosted on your server: 1 Log in to the server you want to administer. 2 Drag the contents of your previous web folder to your new web folder.
LL2350.book Page 26 Friday, August 22, 2003 2:32 PM Changing the Access Port for a Website By default, the server uses port 80 for connections to websites on your server. You may need to change the port used for an individual website, for instance, if you want to set up a streaming server on port 80. Make sure that the number you choose does not conflict with ports already being used on the server (for FTP, Apple File Service, SMTP, and others).
LL2350.book Page 27 Friday, August 22, 2003 2:32 PM To enable or disable the performance cache for your web server: 1 In Server Admin, click Web in the list for the server you want. 2 Click Settings in the button bar. 3 In the Sites pane, double-click the site in the list. 4 In the Options pane, click Performance Cache to change its state. 5 Click Save. Web service restarts. You can also improve server performance by disabling the access log.
LL2350.book Page 28 Friday, August 22, 2003 2:32 PM Understanding the New Web Service access_log Format In version 10.3 of Mac OS X Server, the web performance cache does not prevent a remote client's IP address from being logged in the access_log. The web performance cache process now adds an HTTP header named “PC-Remote-Addr” that contains the client's IP address before passing a request to the Apache web server.
LL2350.book Page 29 Friday, August 22, 2003 2:32 PM Creating Indexes for Searching Website Content Version 10.3 of Mac OS X Server continues to support the mod_sherlock_apple Apache module, which allows web browsers to search the content of your website. As in previous versions of the server, you must produce a content index before content searching is possible. Content indexes in earlier server versions had to be created in Sherlock. Now, you can create content indexes using the Finder.
LL2350.book Page 30 Friday, August 22, 2003 2:32 PM Enabling WebDAV on Websites Web-based Distributed Authoring and Versioning (WebDAV) allows you or your users to make changes to websites while the sites are running. If you enable WebDAV, you also need to assign access privileges for the sites and for the web folders. To enable WebDAV for a site: 1 In Server Admin, click Web in the list for the server you want. 2 Click Settings in the button bar. 3 In the Sites pane, double-click the site in the list.
LL2350.book Page 31 Friday, August 22, 2003 2:32 PM Setting Access for WebDAV-Enabled Sites You create realms to provide security for websites. Realms are locations within a site that users can view or make changes to when WebDAV is enabled. When you define a realm, you can assign browsing and authoring privileges to users of the realm. To add users and groups to a realm: 1 In Server Admin, click Web in the list for the server you want. 2 Click Settings in the button bar.
LL2350.book Page 32 Friday, August 22, 2003 2:32 PM WebDAV and Web Content File and Folder Permissions Mac OS X Server imposes the following constraints on web content files and folders (which are located by default in /Library/WebServer/Documents): • For security reasons, web content files and folders should not be writable by world. • Web content files and folders are owned by user root and group admin by default, so they are modifiable by any administrator but not by user or group www.
LL2350.book Page 33 Friday, August 22, 2003 2:32 PM Enabling a Common Gateway Interface (CGI) Script Common Gateway Interface (CGI) scripts (or programs) send information back and forth between your website and applications that provide different services for the site. • If a CGI is to be used by only one site, install the CGI in the Documents folder for the site. The CGI name must end with the suffix “.cgi.
LL2350.book Page 34 Friday, August 22, 2003 2:32 PM 5 In the General pane, add index.shtml to the set of default index files for that site. Repeat this procedure for each virtual host site that uses SSI. (See “Setting the Default Page for a Website” on page 25 for more information.) By default, the /etc/httpd/httpd.conf file maintained by Server Admin contains the following two lines: AddHandler server-parsed shtml AddType text/html shtml You can add MIME types in Server Admin from the MIME Types pane.
LL2350.book Page 35 Friday, August 22, 2003 2:32 PM To set the server response for a MIME type or content handler: 1 In Server Admin, click Web in the list for the server you want. 2 Click Settings in the button bar. 3 In the MIME Types or content Handlers pane, click the Add button, or select the item in the list you want to edit and click the Edit button. 4 If necessary, type a name for a new MIME type or content handler, then type the file suffix associated with this mapping in the Suffixes field.
LL2350.book Page 36 Friday, August 22, 2003 2:32 PM Setting Up the SSL Log for a Website If you are using Secure Sockets Layer (SSL) on your web server, you can set up a file to log SSL transactions and errors. To set up an SSL log: 1 In Server Admin, click Web for the server you want. 2 Click Settings in the button bar. 3 In the Sites pane, double-click the site you want to edit.
LL2350.book Page 37 Friday, August 22, 2003 2:32 PM Web Service Configuration By default, on Mac OS X Server: • Web service ignores any files in the /etc/httpd/users/ folder. • Workgroup Manager does not make any web service configuration changes. • Folder listings are not enabled for users. All folder listings in web service use Apache's FancyIndexing directive, which makes folder listings more readable. In Server Admin, the Sites/Options pane for each site has a Folder Listing checkbox.
LL2350.book Page 38 Friday, August 22, 2003 2:32 PM If the user has placed multiple content files in his or her Sites folder, and cannot modify the index.html to include links to those files, the user may benefit from the automatic folder indexing described previously. If the “Enable folder listing” setting is enabled, an index listing of file names will be visible to browsers at http://example.com/~refuser. Indexing settings also apply to subfolders placed in the user's Sites folder.
LL2350.book Page 39 Friday, August 22, 2003 2:32 PM Because of the warning message that appears in the web service error log about mod_hfs_apple, there have been questions about the function of mod_hfs_apple. The warning messages do not indicate a problem with the correct function of mod_hfs_apple. You can verify that mod_hfs_apple is operating correctly by creating a security realm and attempting to bypass it with a case-variant of the actual URL.
LL2350.
LL2350.book Page 41 Friday, August 22, 2003 2:32 PM 4 WebMail 4 Enable WebMail for the websites on your server to provide access to basic email operations by means of a web connection. WebMail adds basic email functions to your website. If your web service hosts more than one website, WebMail can provide access to mail service on any or all of the sites. The mail service looks the same on all sites. WebMail Basics The WebMail software is included in Mac OS X Server, but is disabled by default.
LL2350.book Page 42 Friday, August 22, 2003 2:32 PM Users log in to WebMail with the name and password they use for logging in to regular mail service. WebMail does not provide its own authentication. For more information on mail service users, see the mail service administration guide. When users log in to WebMail, their passwords are sent over the Internet in clear text (not encrypted) unless the website is configured to use SSL. For instructions on configuring SSL, see “Enabling SSL” on page 35.
LL2350.book Page 43 Friday, August 22, 2003 2:32 PM 5 In the Sites pane, double-click the site in the list. 6 In the Options pane, select WebMail. 7 Click Save. Web service restarts. Configuring WebMail After enabling WebMail to provide basic email functions on your website, you can change some settings to integrate WebMail with your site. You can do this by editing the configuration file /etc/squirrelmail/config/config.
LL2350.book Page 44 Friday, August 22, 2003 2:32 PM To configure basic WebMail options: 1 In the Terminal application, type the following command and press Return: sudo /etc/squirrelmail/config/conf.pl 2 Follow the instructions displayed in the Terminal window to change SquirrelMail settings as desired. 3 Change the domain name to your server’s real domain name, such as example.com. The domain name is the first item on the SquirrelMail script’s Server Settings menu.
LL2350.book Page 45 Friday, August 22, 2003 2:32 PM 5 Secure Sockets Layer (SSL) 5 Use Secure Sockets Layer to provide secure transactions and encrypted communication to users of the websites on your server. If you want to provide secure transactions on your server, such as allowing users to purchase items from a website, you should set up Secure Sockets Layer (SSL) protection. SSL lets you send encrypted, authenticated information across the Internet.
LL2350.book Page 46 Friday, August 22, 2003 2:32 PM 4 If it doesn’t already exist on your server, create a directory at the location /etc/httpd/ ssl.key. Make a copy of the key.pem file (created in step 2) and rename it server.key. Then copy server.key to the ssl.key directory. 5 At the prompt, type the following command and press Return: openssl req -new -key key.pem -out csr.pem This generates a file named csr.pem in your home directory.
LL2350.book Page 47 Friday, August 22, 2003 2:32 PM • The default certificate format for SSLeay/OpenSSL is PEM, which actually is Base64 encoded DER with header and footer line. For more about the certificate format, see www.modssl.org. After you’ve completed the process, you’ll receive an email message that contains a Secure Server ID. This is your server certificate. When you receive the certificate, save it to your web server’s hard disk as a file named server.crt.
LL2350.book Page 48 Friday, August 22, 2003 2:32 PM Web Server SSL Password Not Accepted When Manually Entered Server Admin allows you to enable SSL with or without saving the SSL password. 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.
LL2350.book Page 49 Friday, August 22, 2003 2:32 PM 6 Working With Open-Source Applications 6 Become familiar with the open-source applications Mac OS X Server uses to administer and deliver web services. Several open-source applications provide essential features of web service. These applications include: • Apache web server • JBoss application server • Tomcat servlet container • MySQL database Apache Apache is the http web server provided with Mac OS X Server.
LL2350.book Page 50 Friday, August 22, 2003 2:32 PM Location of Essential Apache Files Apache configuration files and locations have been simplified in Mac OS X Server 10.3. Locations of key files are as follows: • The Apache configuration file for web service is located in the directory /etc/httpd/. • The site configuration files are located in the directory /etc/httpd/sites.
LL2350.book Page 51 Friday, August 22, 2003 2:32 PM Starting and Stopping Web Service Using the apachectl Script The default way to start and stop Apache on Mac OS X Server is to use the web module of Server Admin. If you want to use the apachectl script to start and stop web service instead of using Server Admin, be aware of the following behaviors: • The web performance cache is enabled by default. When web service starts, both the main web service process (httpd) and a webperfcache process start.
LL2350.book Page 52 Friday, August 22, 2003 2:32 PM m m To enable mod_rendezvous_apple on Mac OS X Server: To enable the module, use the Modules pane in Server Admin. To set up mod_rendezvous_apple on Mac OS X Server: To cause additional logging, which may be helpful if you discover a problem, find the LogLevel directive in httpd.conf and change it to a more verbose setting, such as “info.” Note: Whenever new users are added, restart web service so that their sites are registered.
LL2350.book Page 53 Friday, August 22, 2003 2:32 PM RegisterUserSite directive • Syntax: RegisterUserSite username | all-users | customized users [ registrationNameFormat [port | main] • Default: No registration if directive is absent; registration name defaults to longname. Port defaults to 80, host defaults to local. • Context: server config • Compatibility: Apache 1.3.
LL2350.book Page 54 Friday, August 22, 2003 2:32 PM The optional third argument can be can be used to specify a port number under which the HTTP service is to be registered, or the keyword “main”; in the latter case, the port number of the “main server” (outside any virtual hosts) is used. In the case of Mac OS X Server, do not specify “main” for the port, because all externally visible sites are virtual hosts, and the main server is used only for status. If the port argument is omitted, port 80 is used.
LL2350.book Page 55 Friday, August 22, 2003 2:32 PM Using Apache Axis You can use Apache Axis by writing web applications that use the Axis libraries and then deploy the applications in Tomcat or JBoss. Unlike JBoss and Tomcat, Axis is not usually used as an application server. Mac OS X Server version 10.3 includes a preinstalled version of Apache Axis (1.1), which operates in conjunction with the preinstalled Tomcat 4.1.24-LE. Apache Axis is an implementation of Simple Object Access Protocol (SOAP).
LL2350.book Page 56 Friday, August 22, 2003 2:32 PM If you want to experiment with Apache 2, note the following: • It is installed in a separate location in the file system: /opt/apache2. • It is not connected to Server Admin. • It serves webpages from /opt/apache2/htdocs. • Its configuration is in /opt/apache2/conf/httpd.conf. Apple modified this file by configuring it to run the httpd processes as user and group www.
LL2350.book Page 57 Friday, August 22, 2003 2:32 PM For detailed information about JBoss, J2EE, and the tools, see these guides: • Java application server administration guide, which explains how to deploy and manage J2EE applications using JBoss in Mac OS X Server • Java enterprise applications guide, which explains how to develop J2EE applications Both guides are available from Apple developer publications. Additional information about these Java technologies is available online. • For JBoss, see www.
LL2350.book Page 58 Friday, August 22, 2003 2:32 PM To manage JBoss: 1 In Server Admin, click Application Server. 2 Click Settings in the button bar. 3 Click Manage JBoss. Note: The JBoss management tool must already be running. You can use the Terminal application to set it as a startup item. 4 Make the adjustments you want in the management console. Backing Up and Restoring JBoss Configurations You use the Application Server section of Server Admin to back up and restore JBoss configurations.
LL2350.book Page 59 Friday, August 22, 2003 2:32 PM For information about Java Servlets that you can use on your server, see • http://java.sun.com/products/servlet/ • http://java.sun.com/products/jsp/ If you want to use Tomcat, you must activate it. You can use Server Admin or the command-line tool to start Tomcat. To start Tomcat using Server Admin: 1 In Server Admin, click Application Server in the list for the server you want. 2 Click Settings in the button bar. 3 Click Tomcat Only.
LL2350.book Page 60 Friday, August 22, 2003 2:32 PM Installing MySQL Mac OS X Server versions 10.3 includes the latest MySQL, version 4.0.14. Since it's preinstalled, you won't find it in /usr/local/mysql. Instead, its elements are distributed in the file system according to standard UNIX file layout, with executables in /usr/sbin and /usr/bin, man pages in /usr/share/man, and other parts in /usr/share/mysql. When installed, the MySQL database resides in /var/mysql.
LL2350.book Page 61 Friday, August 22, 2003 2:32 PM 7 Installing and Viewing Web Modules 7 Become familiar with the modules that provide key features and controls for web service. The Apache web server includes a series of modules that control the server’s operation. In addition, Mac OS X Server provides some modules with specialized functions for the Macintosh. Apache Modules Modules “plug in” to the Apache web server software and add functionality to your website.
LL2350.book Page 62 Friday, August 22, 2003 2:32 PM mod_sherlock_apple m This module lets Apache perform relevance-ranked searches of the website using Sherlock. Once you index your site using the Finder, you can provide a search field for users to search your website. To index a folder’s contents, choose Get Info from the file menu. Note: You must be logged in as root for the index to be copied to the web directory in order to be searchable by a browser. Clients must add .
LL2350.book Page 63 Friday, August 22, 2003 2:32 PM PHP: Hypertext Preprocessor PHP lets you handle dynamic web content by using a server-side HTML-embedded scripting language resembling C. Web developers embed PHP code within HTML code, allowing programmers to integrate dynamic logic directly into an HTML script rather than write a program that generates HTML. PHP provides CGI capability and supports a wide range of databases. Unlike client-side JavaScript, PHP code is executed on the server.
LL2350.
LL2350.book Page 65 Friday, August 22, 2003 2:32 PM 8 Solving Problems 8 If you experience a problem with web service or one of its components, check the tips and strategies in this chapter. From time to time you may encounter a problem when setting up or managing web services. Some of the situations that may cause a problem for administering web service or for client connections are outlined here.
LL2350.book Page 66 Friday, August 22, 2003 2:32 PM A Web Module Is Not Working as Expected • Check the error log in Server Admin for information about why the module might not be working correctly. • If the module came with your web server, check the Apache documentation for that module and make sure the module is intended to work the way you expected.
LL2350.
LL2350.
Glossary Glossary LL2350.book Page 69 Friday, August 22, 2003 2:32 PM Apache An open-source HTTP server that is integrated into Mac OS X Server. You can find detailed information about Apache at www.apache.org. application server Software that runs and manages other applications, usually web applications, that are accessed using a web browser. The managed applications reside on the same computer where the application server runs.
LL2350.book Page 70 Friday, August 22, 2003 2:32 PM Mac OS X Server An industrial-strength server platform that supports Mac, Windows, UNIX, and Linux clients out of the box and provides a suite of scalable workgroup and network services plus advanced remote management tools. MySQL An open-source relational database management tool for web servers. open source A term for the cooperative development of software by the Internet community.
LL2350.book Page 71 Friday, August 22, 2003 2:32 PM URL (Uniform Resource Locator) The address of a computer, file, or resource that can be accessed on a local network or the Internet. The URL is made up of the name of the protocol needed to access the resource, a domain name that identifies a specific computer on the Internet, and a hierarchical description of a file location on the computer. user name The long name for a user, sometimes referred to as the user’s “real” name. See also short name.
LL2350.
LL2350.book Page 73 Friday, August 22, 2003 2:32 PM Index Index A J access privileges setting for WebDAV 10 websites 11, 14 Apache module 7, 9, 29, 51, 60, 61 Apache web server 8, 61 configuration 9 Java JavaServer Pages (JSP) with Tomcat 21 servlet (with Tomcat) 21 Tomcat and 21 C CA certificate 45 cache.
LL2350.
LL2350.
