test

Sun WebServer 2.1 Installation Guide

Chapter 4 Migration from Sun WebServer 1.0 to Sun WebServer 2.1

New Terminology/Structure

If you have installed Sun WebServer 2.0, you can upgrade to Sun WebServer 2.1 by uninstalling the reinstalling the software. If you have Sun WebServer 1.0, the Sun WebServer 1.0 configuration files must be converted into files compatible with Sun WebServer 2.1. This document is a guide to this conversion. Refer to the Sun WebServer 2.1 documentation for details on the new features of Sun WebServer 2.1.

Instances and Web Sites

Even though Sun WebServer 1.0 was able to support multiple instances of the HTTP server running concurrently, starting, stopping, and restarting the server worked best with a single instance of the HTTP daemon. Sun WebServer 2.1 improves support for multiple instances by providing each httpd daemon on the system with a unique name. One is able to start, stop, and restart individual instances by using their names. See the man page htserver(1m) for more information.

Sun WebServer 2.1 has also expanded support of virtual hosts. Each virtual host is now associated with a web site and given its own subtree in the file system, which contains the configuration files for that host as well as the host's document root. While Sun WebServer 1.0 maintained all configuration information for a virtual host in the global configuration file httpd.conf, Sun WebServer 2.1 stores most of this information in a site configuration file located relative to the root of the web site. Placing most of the site-specific configuration information at the web site rather than in a single file makes Sun WebServer 2.1 more scalable than Sun WebServer 1.0 and simplifies the administration of individual web sites.

Configuration File Locations

Sun WebServer 1.0 had two primary configuration files in the default location /etc/http/:

Sun WebServer 2.1 partitions the directives in these files into server-level configuration files for server instances and site-level configuration files for individual web sites.

Server-Level Configuration Files

Server-level configuration files are installed in /etc/http/ by default. <instance_name> below is the unique name of the httpd instance using the file. An instance name is associated with a server instance when it is created using the Sun WebServer GUI or the htserver add command.

Site-Level Configuration Files

Site-level configuration files are installed to the web site subtree by default. <site_name> below refers to the name of the web site using this file.

All of the file names listed above are suggested names. The only fixed configuration file name is /etc/http/httpd-instances.conf. Each server instance name and basic configuration file is listed in httpd-instances.conf, and each server configuration file in turn refers to the other configuration files by name.

Command-Line Utilities

Sun WebServer 2.1 has added numerous command line utilities for modification of its configuration files. These utilities are used at various locations in this document to explain migration to Sun WebServer 2.1. Please refer to the Sun WebServer 2.1 man pages for details on all Sun WebServer utilities available from the command line. For the commands referenced in this document, refer to the htserver(1m), hthost(1m), and htrealm(1m) man pages. For information on the referenced configuration files see httpd.conf(4), httpd.site.conf(4), access.conf(4), and realms.conf(4). Sun WebServer 2.1 also has an GUI, located in the package SUNWhtadm, that can be used to administer all aspects of the HTTP server. To access the GUI, you must also install SUNWixklg and SUNWixavm.

Creating a Sun WebServer 2.1 Server

Before converting a Sun WebServer 1.0 configuration into the Sun WebServer 2.1 format, first add a basic Sun WebServer 2.1 instance to the system. This server will contain the general file structure used in Sun WebServer 2.1 and will provide default configuration files that can be modified with the values from the Sun WebServer 1.0 server.

To create a new Sun WebServer 2.1 instance named "server1":

  1. Type the following at the command line (as "root"): 


    # htserver add "server1"

    This command creates a new Sun WebServer 2.1 server-level configuration file and a default web site. The locations where new files are installed are listed below:

    • /etc/http/server1.httpd.conf: Server configuration file

    • /var/http/server1/: Root of the new server

    • /ver/http/server1/websites/default_site/: Site path of default web site

    • /var/http/server1/websites/default_site/conf/: Location of site configuration file

Migrating the Sun WebServer 1.0 httpd.conf File

The Sun WebServer 1.0 /etc/http/httpd.conf file contains the basic directives for configuring the server as a whole, the individual virtual hosts, and the ports. The three primary block types are the server{} block, the url{} block, and the port{} block. Each of these types will be discussed in this section.

server{} Block

Converting the server{} block from Sun WebServer 1.0 to Sun WebServer 2.1 format is relatively straightforward. Most of the directives in 1.0 are the same in 2.1, with the following exceptions listed below:

acl_delegate_depth

The acl_delegate_depth directive, and the concept of delegation of access controls, is no longer supported in Sun WebServer. See "Migrating the Sun WebServer 1.0 access.acl File" in this document.

acl_enable

The acl_enable directive has been changed to access_enable.

To convert the acl_enable directive

  1. Search for the following Sun WebServer 1.0 directive in /etc/http/httpd.conf: 


    acl_enable				yes

  2. Replace it in /etc/http/server1.httpd.conf with the following directive: 


    access_enable 		yes

acl_file

The acl_file directive is no longer supported in the server{} block, because the server-level access control file is now configured to be: /etc/http/access.conf. This file name cannot be changed.

map

The map directive is no longer supported in the server{} block. All URL mappings must be made in a web site's map.conf file.

mime_add

The mime_add directive is no longer supported in Sun WebServer 2.1. All mime types must be specified in the mime.types file at either the server or site level.

To convert the mime_add directive

  1. Given the following Sun WebServer 1.0 directive: 


    server {
	mime_add			"image/.jpeg"			"JPG"
}

  2. Make sure a mime.types file is specified in /etc/http/server1.httpd.conf:

    Note -

    If this file is shared among all the servers, changes will effect all httpd daemons


    server {
	mime_file 			"/etc/http/mime.types
}

  3. Add the new MIME mappings to the /etc/http/mime.types file: 


    image/jpeg 			JPG

server{} Block Conversion

  1. Given the following Sun WebServer 1.0 server{} block in /etc/http/httpd.conf: 


    server {
	server_root							"/var/http/demo/"
	server_user							"root"
	mime_add										"image/jpeg"	"JPG"
	mime_default_type	 text/html
	acl_enable								"yes"
	acl_file										"/etc/http/access.acl"
	acl_delegate_depth			3

	map			/cgi-bin/				/var/http/cgi-bin/			cgi	
}

  2. Modify the server{} block in /etc/http/server1.httpd.conf: 


    server {
	server_root							"/var/http/demo/"
	server_user							"http"
	mime_file									"/etc/http/mime.types"
	mime_default_type	 text/html
	access_enable					"yes"
}

  3. Add the MIME mapping to the /etc/http/mime.types file specified in (2): 


    image/jpeg				JPG

url{} Block

In Sun WebServer 1.0, all the configuration parameters for a virtual host were found in a single location in the /etc/http/httpd.conf file. In Sun WebServer 2.1, global information for the virtual host is located in the server-level configuration file, and more specific information is located in the site-level configuration file.

To convert a Sun WebServer 1.0 url{} block to 2.1

  1. Add a new web site to the 2.1 server using the hthost command line utility.

  2. Modify the new configuration files created with the Sun WebServer 1.0 values, or with Sun WebServer 2.1 equivalents.

To create a 2.1 web site

  1. Add a web site (widgets), to the current server (server1): 


    # hthost add -i server1 -h widgets \
	-s /var/http/server1/websites/widgets

    This will add the following entry to the server-level configuration file, /etc/http/server1.httpd.conf: 


    url //widgets {
	site_enable 				"yes"
	site_path							"/var/http/server1/websites/widgets"
	site_config					"conf/widgets.site.conf"
}

    It will also create a new web site at: /var/http/server1/websites/widgets/. The following configuration files will be placed in the directory /var/http/server1/websites/widgets/conf/:

    • widgets.site.conf

    • access.conf

    • realms.conf

    • map.conf

    • content.conf

    • servlets.properties

Modifying the Server-Level Configuration File

Most of the configuration parameters from the Sun WebServer 1.0 url{} blocks will be placed in the site-level configuration file, widgets.site.conf. One exception is setting the ports on which a virtual host listens. For each virtual host, one must specify on which IP addresses and ports it accepts connections. (This is different than in 1.0, where this information was stored in the port{} blocks using the hosts_supported directive.) IP address:port pairs are termed "connection end points" in Sun WebServer 2.1. All web sites should have their connection end points specified (with the exception of the default web site, which listens on all interfaces and does not allow connection end points to be defined). For more information on connection end points, see httpd.conf (4).

Setting the connection end points of a web site

  1. To have the virtual host, widgets, accept connections on IP address 129.128.127.126 on port 80, and all IP addresses on port 1880, write the following in /etc/http/server1.httpd.conf: 


    url //widgets {
	site_enable					 "yes"
	site_path							 "/var/http/server1/websites/widgets"
	site_config						"conf/widgets.site.conf"
	conn_end_points		129.128.127.126:80:1880
}
Note -

Not specifying IP address to the left of the colon (:) defaults to "all IP addresses" in a HTTP 1.1 virtual host. Also note that all connection end points specified must be mapped by port{} blocks.

Modifying the Site-Level Configuration File

Most of the Sun WebServer 1.0 url{} block configuration directives can be copied directly into the Sun WebServer 2.1 site-level configuration file, /var/http/server1/websites/widgets/conf/widgets.site.conf, with following exceptions:

map

All Sun WebServer 2.1 URL mappings are now stored in a separate file: map.conf.

To convert the map directive

  1. Given the following Sun WebServer 1.0 directive in /etc/http/httpd.conf: 


    url //widgets {
	map 		/cgi-bin/			/var/http/shared/cgi-bin/			cgi
}

  2. Add the following line to the /var/http/server1/websites/widgets/conf/map.conf file at the widgets site: 


    map 		/cgi-bin/			/var/http/shared/cgi-bin/			cgi

mime_add

To convert the mime_add directive

  1. Given the following Sun WebServer 1.0 directive in /etc/http/httpd.conf: 


    url //widgets {
	mime_add 				"image/jpeg"					"JPG"
}

  2. Uncomment the mime_file directive in /var/http/server1/websites/widgets/conf/widgets.site.conf: 


    url //widgets {
	mime_file				"conf/mime.types"
}

  3. Add the new mime mappings to the /var/http/server1/websites/widgets/conf/mime.types file: 


    image/jpeg					JPG

port{} Block

There are two primary changes to the port{} blocks in Sun WebServer 2.1: the hosts_supported directive is no longer valid as the ports a host listens on are now listed using the conn_end_points directive in the url{} block, and all ports must have an ip_address specified. The IP address 0.0.0.0 is special and means "all valid IP addresses on this machine".

To convert a port{} block for a specific IP address

  1. Given the following Sun WebServer 1.0 port{} block: 


    port 80 {
	ip_address									129.128.127.126
	keepalive_enable			"yes"
	request_timeout				180
	hosts_supported					widgets
}

  2. Modify the widgets url{} block in /etc/http/server1.httpd.conf to have conn_end_points specified correctly: 


    url //widgets {
	site_enable 					"yes"
	site_path								"/var/http/server1/websites/widgets"
	site_config						"conf/widgets.site.conf"
	conn_end_points			129.128.127.126:80
}

  3. Add the port{} block to /etc/http/server1.httpd.conf (without the hosts_supported directive): 


    port 80 {
	ip_address									129.128.127.126
	keepalive_enable			"yes"
	request_timeout				180
}
To convert a port{} block for all IP addresses

  1. Given the following Sun WebServer 1.0 port{} block example: 


    port 1880 {
	keepalive_enable				"yes"
	request_timeout					180
	hosts_supported					widgets
}

  2. Modify the widgets url{} block in /etc/http/server1.httpd.conf to have conn_end_points specified correctly: 


    url //widgets {
	site_enable							"yes"
	site_path 								"/var/http/server1/websites/widgets"
	site_config							"conf/widgets.site.conf"
	conn_end_points			:1880
}

  3. Add the ip_address directive with the value 0.0.0.0 to the port{} block in /etc/http/server1.httpd.conf: 


    port 1880 {
	ip_address									0.0.0.0
	keepalive_enable			"yes"
	request_timeout				180
}

Migrating the Sun WebServer 1.0 access.acl File

Access control has changed substantially between Sun WebServer 1.0 and 2.1. Sun WebServer 2.1 access control documentation should be reviewed before attempting to migrate the old Sun WebServer access control structure to the new. The most significant changes are listed below:

To migrate the Sun WebServer 1.0 access.acl file to 2.1, one needs to create or select authentication realms, modify the access control syntax for the mapped URLs to reflect the new 2.1 syntax, and collect the access controls in the access.acl file and delegated files to the access.conf files in each of the individual web sites.

Realms

In Sun WebServer 1.0, the realm directive had little significance other than as an identifier for the browser (printed in the authentication dialog box). In Sun WebServer 2.1, the realm specifies a pre-existing set of users and groups used for authenticating access to a URL. Realm information is stored in the realms.conf file. HTPASSWD realms have a directory associated with them as well (defined in realm.conf) which contains the "users" and "groups" files to be used in the authentication. The password_file and group_file directives in Sun WebServer 1.0 ACLs are therefore obsolete. All 1.0 realms will be HTPASSWD realms in 2.1 since these user-created databases were the only source available in 1.0.

Migrating to Sun WebServer 2.1 realms

  1. Given the following Sun WebServer 1.0 access control in /etc/http/access.acl for host widgets: 


    url /reports {
	realm															Managers
	authentication_type		basic

	password_file							/usr/auth/Managers/Maners_users
	group_file										/usr/auth/Managers/Managers_groups

	+ group														report_managers
	- user															Joe
}

  2. Create a realm to hold the password and group file. This can be done as follows: 


    # htrealm add -i server1 -h widgets -r Managers -s HTPASSWD

    This command will add the following entry to the realms.conf for the site widgets: 


    realm Managers {
	realm_source HTPASSWD
}

    It also creates the following directory at the site widgets: 


    /var/http/server1/websites/widgets/conf/realms/Managers/

  3. Copy the users and groups file into the Managers directory: 


    # cp /usr/auth/Managers/Managers_users \
	/var/http/server1/websites/widgets/conf/realms/Managers/users
# cp /usr/auth/Managers/Managers_groups \
	/var/http/server1/websites/widgets/conf/realms/Managers/groups

  4. Remove the file directives from the Sun WebServer 1.0 ACL and place the new ACL in the Sun WebServer 2.1 ACL file: /var/http/server1/websites/widgets/conf/access.conf: 


    url /reports {
	realm 															Managers
	authentication_type			basic

	+ group 													 report_managers
	- user															Joe
}

Delegation

The concept of delegation has been removed from Sun WebServer 2.1. All the access controls that were previously located within delegated files must be relocated into the single access.conf for a particular site.

Converting a delegated ACL

  1. Given the following Sun WebServer 1.0 ACL and delegated file:

    • ACL in /etc/http/access.acl: 


      url /statistics {
	delegate 		/var/http/acls/.admin_acl
}

    • /var/http/acls/.admin_acl file: 


      realm 									admin
password_file		/usr/auth/admin_user
group_file					/usr/auth/admin_group

+ group								stat_admins

    • These must be collapsed into a single ACL:

      Note -

      The realm admin must have been created first; see the previous example.


      url /statistics {
	realm 		 admin
	+ group		stat_admins
}
Converting a delegated ACL (advanced)

  1. Given the following Sun WebServer 1.0 ACL and delegated file:

    • ACL in access.acl: 


      url /statistics {
	delegate 		/var/http/acls/.admin_acl
}

    • /var/http/acls/.admin_acl file (the ownership of this file is joe:adm) 


      realm 									 admins
password_file			/usr/auth/admin_user
group_file						/usr/auth/admin_group

+ group									stat_admins

  2. These must be collapsed into a single ACL: 


    url /statistics {
	realm					 admins

	administrators {
		user					 joe
		group				 adm
	}

	+ group				stat_admins
}

Sun WebServer Conversion

The example below shows a full conversion of Sun WebServer 1.0 httpd.conf and access.acl files to Sun WebServer 2.1. New 2.1 directives are ignored in the example below, unless they are explicitly required for the conversion.

Sun WebServer 1.0 httpd.conf to 2.1

  1. Given the following Sun WebServer 1.0 /etc/http/httpd.conf file: 


    server {
	server_root								"/var/http/demo"
	server_user								"root"
	mime_file										"/etc/http/mime.types"
	mime_default_type			text/html

	acl_enable									"yes"
	acl_file											"/etc/http/access.acl"
	acl_delegate_depth		3
	cache_enable							"yes"
	cache_small_file_cache_size	8
	cache_large_file_cache_size	256
	cache_max_file_size									1
	cache_verification_time					10

	map			 /cgi-bin/					/var/http/demo/cgi-bin/			cgi
	map				/sws-icons/			/var/http/demo/sws-icons/

	mime_add		"appication/java"				class
	mime_add		"audio/basic"								au
	mime_add		"audio/basic"								snd
}

url {
	doc_root									 "/var/http/demo/public"
	user_doc_enable			"no"
	user_doc_root					"public_html"
	cgi_enable							 "no"
	cgi_dns_enable		"no"
	cgi_suffix_enable	    "no"
	cgi_user										"nobody"
	log_type										"elf"
	log_prefix								"/var/http/logs/http"
	log_max_files						7
	log_cycle_time					1440
	log_max_file_size		1048576
	ssi_enable									"no"
	ssi_exec											"no"
	ssi_xbithack							"off"

	mime_add								"application/x-csh"		csh
	mime_add								"application/xsh"				sh
}

url //widgets {
	doc_root								 "/var/http/widgets/public"
	user_doc_enable		"yes"
	user_doc_root				"public_html"
	cgi_enable						 "yes"
	cgi_dns_enable			"yes"
	cgi_suffix_enable	 "yes"
	cgi_user									"nobody"

	log_type								"clf"
	log_prefix						"/var/http/logs/widgets"
	log_max_files				7
	log_cycle_time			1440
	log_max_file_size		1048576
	ssi_enable							"yes"
	ssi_exec									"yes"
	ssi_xbithack					"full"

	map 		/cgi-bin/				/var/http/widgets/cgi-bin/		cgi
	map 		/sws-icons/		/var/http/widgets/sws-icons/
}

port 80 {
	keepalive_enable			"yes"
	request_timeout				180
}

port 1880 {
	ip_address										129.128.127.126
	keepalive_enable			"yes"
	request_timeout				180
	hosts_supported				widgets
}

  2. Create a new server for conversion (we will modify the configuration files that are created for the new server with the 1.0 values): 


    #htserver add "server1"

  3. Add a web site, widgets: 


    # hthost add -i server1 -h widgets \
	-s /var/http/server1/websites/widgets

  4. Modify the server-level file /etc/http/server1.httpd.conf: 


    server {
	server_root						"/var/http/server1/"
	server_user						"root"
	mime_file								"/etc/http/mime.types"
	mime_default_type	 	text/html
	access_enable					"yes"
	cache_enable						"yes"
	cache_small_file_cache_size		8
	cache_large_file_cache_size		256
	cache_max_file_size									 1
	cache_verification_time					 10
}

url {
	site_path					/var/http/server1/websites/default_site
	site_config			"conf/default_site.site.conf"
	site_enable			"yes"
}

url //widgets {
	site_enable				"yes"
	site_path						"/var/http/server1/websites/widgets"
	site_config				"conf/widgets.site.conf"
	conn_end_points	129.128.127.126:1880 :80
}

port 80 {
	ip_address							0.0.0.0
	keepalive_enable	"yes"
	request_timeout		180
}

port 1880 {
	ip_address						129.128.127.126
	keepalive_enable	"yes"
	request_timeout			180
}

  5. Modify /etc/http/mime.types: 


    application/java				class
audio/basic									au snd

  6. Modify /var/http/server1/websites/default_site/conf/default_site.site.conf: 


    url {
	doc_root						/var/http/demo/public

	map_file						conf/map.conf
	realm_file				conf/realms.conf
	access_file			conf/access.conf
	content_file		conf/content.conf
	mime_file					conf/mime.types

	user_doc_enable		"no"
	user_doc_root				"public_html"
	cgi_enable							"no"
	cgi_dns_enable			"no"
	cgi_suffix_enable	"no"
	cgi_user									"nobody"
	log_type									"elf"
	log_prefix							"/var/http/server1/logs/default"
	log_max_files					7
	log_cycle_time				1440
	log_max_file_size	 1048576
	ssi_enable							"no"
	ssi_exec									"no"
	ssi_xbithack					"off"
}

  7. Create /var/http/server1/websites/default_site/conf/mime.types: 


    application/x-csh			csh
application/x-sh				sh

  8. Modify /var/http/server1/websites/default_site/conf/map.conf: 


    map 		/cgi-bin/				 /var/http/demo/cgi-bin/		cgi
map			/sws-icons/			/var/http/demo/sws-icons/

  9. Modify /var/http/server1/websites/widgets/conf/widgets.site.conf: 


    url {
	doc_root						/var/http/widgets/public

	map_file						conf/map.conf
	realm_file				conf/realms.conf
	access_file			conf/access.conf
	content_file		conf/content.conf
	mime_file					conf/mime.types

	user_doc_enable			"yes"
	cgi_enable							 "yes"
	cgi_dns_enable				"yes"
	cgi_suffix_enable	 "yes"
	cgi_user									 "nobody"
	log_type									 "clf"
	log_prefix							 "/var/http/server1/logs/widgets"
	log_max_files					7
	log_cycle_time				1440
	log_max_file_size		1048576
	ssi_enable								"yes"
	ssi_exec										"yes"
	ssi_xbithack					  "full"
}

  10. Modify /var/http/server1/websites/widgets/conf/map.conf: 


    map 	/cgi-bin/				 /var/http/widgets/cgi-bin/ 	cgi
map 	/sws-icons/			/var/http/widgets/sws-icons/
Sun WebServer 1.0 access.acl to 2.1

  1. Given the following Sun WebServer 1.0 /etc/http/access.acl file and delegated file /var/http/widgets/widgets.acl:

    • /etc/http/access.acl: 


      url "/sws-administration" {
	authentication_type			md5
	realm																serverAdmin
	password_file								 /etc/http/swsadmin.pw
	+ user															 *
}

url "/statistics" {
	authentication_type			basic
	realm																statsRealm
	password_file								/var/http/demo/stats/usrs
	group_file											/var/http/demo/stats/grps
	+ user															*
}

url "//widgets" {
	delegate										/var/http/widgets/widgets.acl
}

    • /var/http/widgets/widgets.acl: 


      url "/" {
	authentication_type			basic
	realm																widgetsRealm
	password_file								/var/http/widgets/users
	group_file											/var/http/widgets/groups

	+ user						 *
	- user						 Joe
	- group						thoseDenied
}

  2. Create a global serverAdmin realm (in /etc/http/realms/), and replace its users file with /etc/http/swsadmin.pw

    Note -

    If the realm already exists, then run just the copy command. 


    # htrealm add -r serverAdmin -s HTPASSWD
# cp /etc/http/swsadmin.pw /etc/http/realms/serverAdmin/users

  3. Create a global statsRealm and replace its users and groups files with those specified in the "/statistics" URL above. Add this new realm to the realms.conf files of both the default site and the widgets site:

    Note -

    <hostname> below refers to the hostname of the workstation, which is used to specify the default site.


    # htrealm add -r statsRealm -s HTPASSWD
# cp /var/http/demo/stats/usrs /etc/http/realms/statsRealm/users
# cp /var/http/demo/stats/grps /etc/http/realms/statsRealm/groups
# htrealm add -i server1 -h widgets -r statsRealm \
	-s HTPASSWD -d /etc/http/realms/statsRealm
# htrealm add -i server1 -h <hostname> -r statsRealm \
	-s HTPASSWD -d /etc/http/realms/statsRealm

  4. Create a local widgetsRealm at the widgets site and replace its users and groups files with those specified above: 


    # htrealm add -i server1 -h widgets -r widgetsRealm -s HTPASSWD
# cp /var/http/widgets/users \
	var/http/server1/websites/widgets/conf/realms/widgetsRealm/
# cp /var/http/widgets/groups \
	/var/http/server1/websites/widgets/conf/realms/widgetsRealm/

  5. Modify /etc/http/access.conf: 


    url /sws-administration {
	authentication_type				md5
	realm																	serverAdmin

	+ user																*
}

  6. Modify /var/http/server1/websites/default_site/conf/access.conf: 


    # Specify /sws-administration ACL here for site administration,
# 	create a siteAdmin realm and add administrators to that realm
# url "/sws-administration" {
# 	authentication_type			md5
# 	realm																siteAdmin
# 	+ user															*
# }

url "/statistics" {
	authentication_type				basic
	realm 																statsRealm

	+ user																*
}

  7. Modify /var/http/server1/websites/widgets/conf/access.conf: 


    # Specify /sws-administration ACL here for site administration
url "/statistics" {
	authentication_type				basic
	realm																	statsRealm

	+ user															*
}

url "/" {
	authentication_type				basic
	realm															 		widgetsRealm

	+ user																*
	- user																Joe
	- group															thoseDenied
}