Chapter 4   Configuring Server Preferences

This chapter describes the proxy server's system settings and tells you how to configure them. System settings affect the entire proxy server. They include options such as the user account the proxy server uses and the port to which it listens.

For directions on starting and stopping the server, see Starting and Stopping iPlanet Web Proxy Server.

Starting and Stopping the Proxy Server

---

There are several methods by which you can start and stop your proxy server. One of these methods is to use the Server On/Off form in the Server Manager. Other methods for starting and stopping your proxy server are discussed in Chapter 1 "Starting the Administration and Proxy Servers."

To use the Server On/Off form to start or stop the proxy server,

1. From the Server Manager, choose Server Preferences|On/Off.
2. Click the Server On or Server Off button.

Viewing Server Settings

---

During installation, you configure some settings for your proxy server. You can view these and other system settings from the Server Manager. The View Server Settings form lists all of the settings for your proxy server. This form also tells you if you have unsaved and unapplied changes, in which case you should save the changes and restart the proxy server so it can begin using the new configurations.

There are two types of settings, technical and content. The proxy server's technical settings come from the magnus.conf file, and the content settings come from the obj.conf file. These files are located in the server root directory in the subdirectory called admin-serv/proxy-id. For more information about the magnus.conf file and obj.conf files, see Appendix C "Proxy Configuration Files."

To view the settings for your server, in the Server Manager, choose Server Preferences|View Server Settings. This list explains the server's technical settings:

• Server Root is the directory where the server binaries are kept. You first specified this directory during installation.
• Hostname is the URL clients will use to access your server.
• Port is the port on your system to which the server listens for HTTP requests.
• Error log is the name and path of the server's error log file.
• User is the user the server runs as.
• Processes is the number of processes your server uses when it starts.
• DNS shows whether DNS is enabled or disabled.

The server's content settings depend on how you've configured your server. Typically, the proxy lists all templates, URL mappings, and access control. For individual templates, this form lists the template name, its regular expression, and the settings for the template (such as cache settings).

Restoring and Viewing Backup Configuration Files

---

You can view or restore a backup copy of your configuration files (magnus.conf, obj.conf, bu.conf, mime.types, and genwork.proxy-id.acl). This feature lets you go to a previous configuration if you're having trouble with your current configuration. For example, if you make lots of changes to the proxy's configuration and then the proxy doesn't work the way you thought it should (for example, you denied access to a URL but the proxy will service the request), you can revert to a previous configuration and then redo your configuration changes.

To view a previous configuration:

1. From the Server Manager, choose Server Preferences|Restore Configuration. The Restore Configuration form appears. The form lists all of the previous configurations ordered by date and time.
2. Click the View button for the version you want to display. A listing of the technical and content settings in that configuration appears.

To restore a backup copy of your configuration files:

1. From the Server Manager, choose Server Preferences|Restore Configuration.
2. Click Restore for the version you want to restore.

If you want to restore all files to their state at a particular time, click the Restore to time button on the left-most column of the table (time being the date and time to which you want to restore).

You can also set the number of backups displayed on the Restore Configuration form. To set the number of backups displayed:

1. In the Server Manager, choose Server Preferences|Restore Configuration.
2. In the "Set number of sets of backups" field, enter the number of backups you want to display.
3. Click the Change button.

Changing System Specifics

---

The System Specifics form lets you set up or change the basic aspects of your server. The form allows you to change the server port, server user, authentication password, and proxy timeout for your proxy server. It also allows you to enable DNS, ICP and proxy arrays. And for the UNIX server, it shows the number of processes or process life. You can also enable or disable DNS from the System Specifics form.

To change the system specifics options:

1. In the Server Manager, choose System Settings|System Specifics.

The System Specifics form appears.

2. Change the options as needed, and then click OK.

The options are described in the following sections.

Make sure you save and apply the changes.

Bind Address

Bind address is the IP address to which this instance of iPlanet Web Proxy Server should listen. You only need to specify a bind address if your machine is answering multiple IP addresses.

Server Port

The server port specifies the number of the TCP port to which the proxy listens. The number you choose is used by proxy users when configuring their web browsers to use the proxy server. Users must specify this server name and port number to get access through the proxy server.

Port numbers for all network-accessible services are maintained in the /etc/services file and yp services on UNIX machines. The standard Telnet port number is 23, and the standard HTTP port number is 80. Because the proxy is not a regular HTTP server, you shouldn't use port 80. Proxies haven't been assigned an official, industry-standard port number.

A recommended proxy port number is 8080. When configuring client programs to use this proxy server, you have to tell them both the host name and the port number. For example, you would use this line in the proxy preferences dialog box in Netscape Navigator:

proxy.netscape.com 8080

---

Note	If you use proxy's SOCKS daemon feature, the proxy should listen to the standard SOCKS port (1080).

---

If you aren't sure if the port number you plan to use is available, check in the /etc/services file on the server machine. Technically, the proxy port number can be any port from 1 to 65535. On a UNIX machine, if you aren't running as root or superuser when you install or start the proxy, you'll have to use a number greater than 1024.

Server User

The server user is the user account that the proxy uses. The user name you enter as the proxy server user should already exist as a normal user account. When the server starts, it runs as if it were started by this user.

If you want to avoid creating a new user account, you can choose an account used by another HTTP server running on the same host, or if you are running a UNIX proxy, you can choose the user nobody. However, on some systems the user nobody can own files but can't run programs, which would make it unsuitable as the proxy user name.

On a UNIX machine, all the processes that the proxy spawns are assigned to the server user account.

Instructions for creating a new user on your UNIX system can be found in your system manual or a UNIX administrator's handbook.

Processes

The processes field shows how many background processes are available to service requests. When individual users send requests to the proxy server, the proxy uses background processes to service their requests. You can specify the number of processes dedicated to the proxy. These processes are spawned when the server starts and they remain idle until needed. Base your choice on achieving a balance between system load and server requests:

The process table of the proxy's system limits the number of processes the proxy can use.

• On a high-demand system, with more than a dozen users, the server requires many of these processes, for example, 80 processes, to handle many simultaneous requests.
• On a low-demand system with less than a dozen users, where only a few simultaneous connections are active at a time, 20 to 40 processes should be sufficient.




---

Note

Depending upon the platform, each process uses the following amount of RAM when idle: AIX: 2.5 Mb HP-UX: 3.3 Mb Solaris: 5 Mb The amount of RAM used by each process can increase by 10% when the process is active. If you specify more processes than can fit simultaneously in main memory, the system starts swapping in virtual memory, which slows down proxy service. All proxy processes must fit in main memory simultaneously to make the proxy efficient.

---

Table 4-1 lists suggested numbers of processes. Use this table to determine the number of processes for your proxy server. You will have to use the extended or extended-2 access log file format to capture the data you'll need to use this table. Before you can use Table 4-1 you must know how long requests take and how many requests the proxy receives per second.

• To find the average service time per request, look at the access log file.
• To estimate the average number of new requests per second, view the access log during peak hours. Use tail -f to continuously view the access log file as the proxy adds entries to it. As entries are added, base your estimate on the number of users and how active they are.




---

Note	The operating system on which you are running your proxy server may limit the number of processes per user. If you need more processes for your proxy server, change the process settings for your operating system.

---

You can change the number of processes at any time using the online form (System Settings|System Specifics), or you can change the number in the magnus.conf file manually (see MaxProcs).

If the server seems slow or is not responding, especially during peak hours, you should increase the number of processes available to the proxy. You might have to increase the RAM or the size of the operating system's process table before you increase the number or processes. For details on changing the operating system's RAM or process table, see the system administration documentation provided with your system.

Table 4-1    Suggested number of processes based on average request service time and number of requests

		Average number of seconds of service time per request
		1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16
Average number of new requests per second	1	10	10	10	15	15	20	20	20	25	25	30	30	30	35	35	40
	2	10	15	15	20	25	25	30	30	35	40	40	45	45	50	55	55
	3	15	20	20	25	30	35	40	40	45	50	55	60	60	65	70	75
	4	15	20	25	30	35	40	45	50	55	60	65	70	75	80	85	90
	5	20	25	30	40	45	50	55	60	70	75	80	85	90	100	105	110
	6	25	30	35	45	50	60	65	70	80	85	95	100	105	115	120	130
	7	25	35	40	50	60	65	75	80	90	100	105	115	120	130	140	145
	8	30	40	45	55	65	75	85	90	100	110	120	130	135	145	155	165
	9	30	40	50	60	70	80	90	100	110	120	130	140	150	160	170	180
	10	35	45	55	70	80	90	100	110	125	135	145	155	165	180	190	200
	12	40	55	65	80	95	105	120	130	145	160	170	185	195	210	225	235
	14	45	60	75	90	105	120	135	150	165	180	195	210	225	240	255	270
	16	55	70	85	105	120	140	155	170	190	205	225	240	255	275	290	310
	18	60	80	95	115	135	155	175	190	210	230	250	270	285	305	325	345
	20	65	85	105	130	150	170	190	210	235	255	275	295	315	340	360	380
	22	70	95	115	140	165	185	210	230	255	280	300	325	345	370	395	415
	24	75	100	125	150	175	200	225	250	275	300	325	350	375	400	425	450
	26	85	110	135	165	190	220	245	270	300	325	355	380	405	435	460	490
	28	90	120	145	175	205	235	265	290	320	350	380	410	435	465	495	525
	30	95	125	155	190	220	250	280	310	345	375	405	435	465	500	530	560
	35	110	145	180	220	255	290	325	360	400	435	470	505	540	580
	40	125	165	205	250	290	330	370	410	455	495	535	575
	45	140	185	230	280	325	370	415	460	510	555	600
	50	155	205	255	310	360	410	460	510	565
	55	170	225	280	340	395	450	505	560
	60	185	245	305	370	430	490	550
	65	200	265	330	400	465	530	595
	70	215	285	355	430	500	570

Process Life

The process life is the number of requests that each server child process services before it exits and gets respawned by the master process. The process life allows memory fragmentation to be cleaned.

DNS

A Domain Name Service (DNS) restores IP addresses into host names. When a web browser connects to your server, the server gets only the client's IP address, for example, 198.95.251.30. The server does not have the host name information, such as www1.netscape.com. For access logging and access control, the server can resolve the IP address into a host name. On the System Specifics form, you can tell the server whether or not to resolve IP addresses into host names.

ICP

The Internet Cache Protocol (ICP) is a message-passing protocol that enables caches to communicate with one another. Caches can use ICP to send queries and replies about the existence of cached URLs and about the best locations from which to retrieve those URLs. You can enable ICP on the System Specifics form. For more information on ICP, see Routing Through ICP Neighborhoods.

Proxy Array

A proxy array is an array of proxies serving as one cache for the purposes of distributed caching. If you enable the proxy array option on the System Specifics form, that means that the proxy server you are configuring is a member of a proxy array, and that all other members in the array are its siblings. For more information on using proxy arrays, see Routing through Proxy Arrays.

Parent Array

A parent array is a proxy array that a proxy or proxy array routes through. So, if a proxy routes through an upstream proxy array before accessing a remote server, the upstream proxy array is considered the parent array. For more information on using parent arrays with your proxy server, see Routing Through a Parent Array.

Proxy Timeout

The proxy timeout is the maximum time between successive network data packets from the remote server before the proxy server times out the request. The default value for proxy timeout is 5 minutes.

---

Note	When the remote server uses server-push and the delay between pages is longer than the proxy timeout, the connection could be terminated before the transmission is done. Instead, use client-pull, which sends multiple requests to the proxy.

---

Creating MIME Types

---

A MIME (Multi-Purpose Internet Mail Extension) type is a standard for multimedia e-mail and messaging. So that you can filter files depending on their MIME type, the proxy server provides a form that lets you create new MIME types for use with your server. The proxy adds the new types to the mime.types file (described on page 261). See "Filtering by MIME Type" on page 156 for more information on blocking files based on MIME types.

To add a MIME type:

1. In the Server Manager, choose System Settings|MIME Types.
2. The form that appears shows all the MIME types listed in the proxy's mime.types file.

• You can edit any MIME type by clicking the link for any part of the MIME type.
• To create a new MIME type, click the New Type button at the bottom of the form.

3. The form that appears is blank if you're creating a new type, or it displays the MIME type you want to edit. The fields on this form are:

• Type is the category of MIME type. This can be type, enc, or lang, where type is the file or application type, enc is the encoding used for compression, and lang is the language encoding.
• MIME Type defines the content type that appears in the HTTP header. The receiving client (such as Netscape Navigator) uses the header string to determine how to handle the file (for example, by starting a separate application or using a plug-in application). The standard strings are listed in RFC 1521.
• File Suffix refers to the file extensions that map to the MIME type. To specify more than one extension, separate the entries with a comma. The file extensions should be unique. That is, you shouldn't map one file extension to two MIME types.

4. Click OK to submit the form. Save and apply your changes.

Understanding DNS Caching

iPlanet Web Proxy Server supports DNS caching to reduce the number of DNS lookups performed by the proxy while it resolves DNS host names into IP addresses.

How DNS Caching Works

The DNS caching feature uses a memory-mapped, shared file to store cached DNS data for all proxy server child processes. By default, this file is an invisible file called /tmp/dnscache.8080. An invisible file is one that remains open but does not appear in the file system's directory structure. You can make the DNS cache file visible by choosing System Settings|Tuning from the Server Manager and selecting the On radio button next to the words, "DNS cache file visible".

This shared memory area is protected by a number of semaphores, named /tmp/dnssema.8080.n, where the value of n can be 1 through the total number of semaphores set in the DNS Cache Configuration page. Each semaphore protects a portion of the shared memory file. By having several semaphores, you avoid potential semaphore congestion, and multiple processes can simultaneously access the shared memory DNS cache (although they access different parts).

Configuring the DNS Cache

From the DNS Cache Configuration page you can specify:

• DNS cache directory
• size of the DNS cache
• number of semaphores to protect the shared memory file
• expiration of DNS cache entries

DNS Cache Directory Location

The DNS cache directory is /tmp by default. You may set the DNS cache directory to any directory that is writable by the proxy process and has enough disk space to hold the DNS cache file.

DNS Cache Size Setting

The size of the DNS cache is expressed in kilobytes. By default, the size is set to 512 kilobytes (.5 MB).

DNS Cache Semaphores

The number of semaphores you need depends on how many processes there are in the server child process pool (the MaxProcs setting). If the proxy handles only a light load, a single or a few semaphores is sufficient. However, if the load is substantial or heavy, and MaxProcs is high (say over a hundred processes), there should be more semaphores to allow more processes to access the DNS cache simultaneously.

The default value is 4 semaphores, which means that at most four processes can simultaneously look up or store data to or from the DNS cache. Unless performance seems to improve by increasing this number, four is a good default value. Having too many semaphores can also hurt the performance.

DNS Cache Entry Expiration

The proxy server purges DNS cache entries from the cache when it reaches a pre-set expiration time. Because the standard gethostbyname() interface to the system resolves the host names, the explicit expiration information provided by the DNS is not available to the proxy's DNS cache.

By default, the DNS expiration time is 1 hour (3600 seconds).

Setting Levels of DNS Subdomains

Some URLs contain host names with many levels of subdomains. It can take the proxy server a long time to do DNS checks if the first DNS server can't resolve the host name. You can set the number of levels that the proxy server will check before returning a "host not found" message to the client.

For example, if the client requests http://www.sj.ca.netscape.com/index.html, it could take a long time for the proxy to resolve that host into an IP address because it might have to go through 4 DNS servers to get the IP address for the host computer. Because these lookups can take a lot of time, you can configure the proxy server to quit looking up an IP address if the proxy has to use more than a certain number of DNS servers.

To set the levels of subdomains the proxy traverses,

1. In the Server Manager, choose System Settings|DNS Subdomains.
2. Choose the template you want to use or choose the entire server.
3. Select the number of levels from the drop-down list.
4. Click OK.Be sure to save and apply your changes.

Disabling HTTP Keep-Alive

---

The proxy supports HTTP keep-alive packets. The keep-alive sub-system is enabled by default in the version 3.6 Service Pack 3 release of the Sun ONE Web Proxy Server. Keep-alives are a TCP/IP feature that keeps a connection open after the request is complete, so that the client can quickly reuse the open connection.

In normal client-server transactions on the web, the client can make several connections to the server that requests multiple documents. For example, if the client requests a web page that has several graphic images, the client needs to make separate requests for each graphic file. Reestablishing connections is time consuming.

By default, keep-alives are enabled on your proxy.

To disable keep-alives, complete the following steps:

1. In the Server Manager, choose System Settings|HTTP Keep-Alive.
2. Choose the template you want to use or choose the entire server.
3. Check Off, and then click OK. Be sure to save and apply your changes.

Allowing or Blocking Arbitrary Methods

---

The proxy can be configured to allow or block arbitrary methods by editing the obj.conf file found in <server-root>/config directory. For more information, see proxy-retrieve (retrieving documents with the proxy).

WebDAV Support

---

The proxy provides support for the Web Distributed Authoring and Versioning protocol. The methods supported are:

• PROPFIND
• PROPPATCH
• MKCOL
• COPY
• LOCK
• UNLOCK
• DELETE

You can however configure the proxy server to support additional arbitrary WebDAV methods. For more information, see proxy-retrieve (retrieving documents with the proxy).

The response returned by WebDAV requests is the 207 Multi-Status response.