Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Web Proxy Server 4.0.1 Administration Guide 

Chapter 7
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. The settings include options such as the user account the proxy server uses and the port to which it listens.

This chapter contains the following sections:

Starting the Proxy Server

This section describes how to start the Proxy Server on different platforms. Once the server is installed, it runs, listening for and accepting requests.

To start the Proxy Server from the administration interface
  1. Access the Server Manager and click the Preferences tab.
  2. Click the Start/Stop Server link. The Start/Stop Server page displays.
  3. Click the On button.

The status of the server appears in the Start/Stop Server page.

To start the Proxy Server on UNIX or Linux
To start the Proxy Server on Windows

Starting SSL-enabled Servers

To start an SSL-enabled server, a password is required. Although you can start an SSL-enabled server automatically if you keep the password in plain text in a file, this is not recommended.

Caution

Leaving the SSL-enabled servers password in plain text in the servers start script is a large security risk. Anyone who can access the file has access to the SSL-enabled server’s password. Consider the security risks before keeping the SSL-enabled server’s password in plain text.

The server’s start script, key pair file, and the key password should be owned by root (or, if a non-root user installed the server, that user account), with only the owner having read and write access to them.

To start your SSL-enabled server automatically on UNIX or Linux
  1. Using a text editor, open the start file.
  2. Locate the -start line in the script and insert the following:

    3. echo "password"|

    where password is the SSL password you have chosen.

    For example, if the SSL password is examples, the edited line might look like this:

    -start)

    echo "examples"|./$PRODUCT_BIN -d $PRODUCT_SUBDIR/config $@

Stopping the Proxy Server

This section describes the various methods to stop the Proxy Server on different platforms.

To stop the Proxy Server from the administration interface
  1. Access the Server Manager and click the Preferences tab.
  2. Click the Start/Stop Server link. The Start/Stop Server page displays.
  3. Click the Off button.

The status of the server appears in the Start/Stop Server page.

To stop the Proxy Server on UNIX or Linux

After you shut down the server, it may take a few seconds for the server to complete its shut-down process and for the status to change to Off.

If your system crashes or is taken offline, the server stops and any requests it was servicing may be lost.

Note

If you have a security module installed with your server, you will be required to enter the appropriate passwords before starting or stopping the server.

To stop the Proxy Server on Windows

Restarting the Proxy Server

This section describes the various methods to restart the Proxy Server on different platforms.

Restarting the Server (UNIX or Linux)

You can restart the server using one of the following methods:

Because the installation scripts cannot edit the /etc/rc.local or /etc/inittab files, you must edit those files with a text editor. If you do not know how to edit these files, consult your system administrator or system documentation.

To restart the Proxy Server from the command line
  1. Log in as root if the server runs on ports with numbers lower than 1024; otherwise, log in as root or with the servers user account.
  2. At the command-line prompt, type the following line and press Enter:

    3. server_root/proxy-serverid/restart

    where server_root is the directory where you installed the server.

  3. You can use the optional parameter -i at the end of the line. The -i option runs the server in inittab mode, so that if the server process is ever killed or crashed, inittab will restart the server for you. This option also prevents the server from putting itself in a background process.
To restart the server using inittab

Add the following text on one line in the /etc/inittab file:

prxy:23:respawn:server_root/proxy-serverid/start -start -i

where server_root is the directory where you installed the server, and proxy-serverid is the server’s directory.

The -i option prevents the server from putting itself in a background process.

You must remove this line before you stop the server.

To restart the server using System RC Scripts

If you use /etc/rc.local, or your system’s equivalent, place the following line in /etc/rc.local:

server_root/proxy-serverid/start

Replace server_root with the directory where you installed the server.

Restarting the Server (Windows)

You can restart the server by

To restart the server on Windows
  1. Use Control Panel > Administrative Tools > Services >
  2. Select Sun Java System Web Proxy Server 4.0 (proxy-serverid) from the list of services.
  3. Change the Startup type to Automatic in the Properties window to have your system start the server each time the computer starts or reboots.
  4. Click OK.

Setting the Termination Timeout

When the server is off, it stops accepting new connections. Then it waits for all outstanding connections to complete. The time the server waits before timing out is configurable in the magnus.conf file. By default it is set to 30 seconds. To change the value, add the following line to magnus.conf file:

TerminateTimeout seconds

where seconds represents the number of seconds the server will wait before timing out.

The advantages to configuring this value is that the server will wait longer for connections to complete. However, because servers often have connections open from nonresponsive clients, increasing the termination timeout may increase the time it takes for the server to shut down.

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 page lists all of the settings for your Proxy Server. This page 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 server’s content settings depend on how you have configured your server. Typically, the proxy lists all templates, URL mappings, and access control. For individual templates, this page lists the template name, its regular expression, and the settings for the template such as cache settings.

The proxy server’s technical settings come from the magnus.conf file and the server.xml file, and the content settings come from the obj.conf file. These files are located in the server root directory in the subdirectory called proxy-id/config.

To view the settings for the Proxy Server
  1. Access the Server Manager and click the Preferences tab.
  2. Click the View Server Settings link. The View Server Settings page displays.

Viewing and Restoring Backups of Configuration Files

You can view or restore a backup copy of your configuration files (server.xml, magnus.conf, obj.conf, mime types, server.xml.clfilter, magnus.conf.clfilter, obj.conf.clfilter, socks5.conf, bu.conf, icp.conf, parray.pat, parent.pat, proxy-id.acl). This feature lets you go to a previous configuration if you are having trouble with your current configuration. For example, if you several changes to the proxy’s configuration and then the proxy does not 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. Access the Server Manager and click the Preferences tab.
  2. Click the Restore Configuration link. The Restore Configuration page displays. The page lists all the previous configurations ordered by date and time.
  3. Click the View link to display a listing of the technical and content settings of a particular version.
To restore a backup copy of your configuration files
  1. Access the Server Manager and click the Preferences tab.
  2. Click the Restore Configuration link. The Restore Configuration page displays. The page lists all the previous configurations ordered by date and time.
  3. Click the Restore link for the version you want to restore.

    4. If you want to restore all files to their state at a particular time, click the Restore to time link 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 page.

To set the number of backups displayed
  1. Access the Server Manager and click the Preferences tab.
  2. Click the Restore Configuration link. The Restore Configuration page displays.
  3. In the Set Number Of Sets Of Backups field, enter the number of backups you want to display.
  4. Click the Change button.

Configuring System Preferences

The Configure System Preferences page lets you set up or change the basic aspects of your server. The page allows you to change the server user, the number of processes, listen queue size, proxy timeout, and timeout after interrupt for your proxy server. It also allows you to enable DNS, ICP, proxy arrays, and parent arrays.

To modify the system preferences
  1. Access the Server Manager and click the Preferences tab.
  2. Click the Configure System Preferences link. The Configure System Preferences page displays.
  3. Change the options as required, and then click OK.
  4. Click Restart Required. The Apply Changes page displays.
  5. Click the Restart Proxy Server button to apply the changes.

The options are described in the following sections.

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 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 cannot run programs, which would make it unsuitable as the proxy user name.

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

Processes

The Processes field shows how many processes are available to service requests. By default, the value is 1. Do not modify this setting unless required.

Listen Queue Size

The Listen Queue Size field specifies the maximum number of pending connections on a listen socket.

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.18.251.30. The server does not have the host name information, such as www.example.com. For access logging and access control, the server can resolve the IP address into a host name. On the Configure System Preferences page, 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 Configure System Preferences page. 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 Configure System Preferences page, 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 Parent Arrays.

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.

Tuning the Proxy Server

The Tune Proxy page allows you to change the default parameters to tune your proxy server’s performance.

To change the default tuning parameters
  1. Access the Server Manager and click the Preferences tab.
  2. Click the Tune Proxy link. The Tune Proxy page displays.
  3. You may want to modify the width of FTP listings to better suit your needs. Increasing listing width allows longer file names and thus reduces file name truncation. The default width is 80 characters.
  4. Click OK.
  5. Click Restart Required. The Apply Changes page displays.
  6. Click the Restart Proxy Server button to apply the changes.

Adding and Editing Listen Sockets

Before the server can process a request it must accept the request via a listen socket, then direct the request to the correct server. When you install the Proxy Server one listen socket, ls1, is created automatically. This listen socket uses the IP address 0.0.0.0 and the port number you specified as your proxy server port number during installation. You cannot delete the default listen socket.

Listen sockets are added, edited, and deleted using the Server Manager’s Add Listen Socket and Edit Listen Sockets pages.

This section contains the following topics:

Adding Listen Sockets

To add listen sockets
  1. Access the Server Manager and click the Preferences tab.
  2. Click the Add Listen Socket link. The Add Listen Socket page displays.
  3. Specify the internal name for the listen socket. You cannot change this name after the listen socket has been created.
  4. Specify the IP address of the listen socket. Can be in dotted-pair or IPv6 notation. Can also be 0.0.0.0, any, ANY or INADDR_ANY (all IP addresses).
  5. Specify the port number to create the listen socket on. Legal values are 1 - 65535. On UNIX, creating sockets that listen on ports 1 - 1024 requires superuser privileges. Configure an SSL listen socket to listen on port 443.
  6. Specify the server name to be used in the host name section of any URLs the server sends to the client. This affects URLs that the server automatically generates but does not affect the URLs for directories and files stored in the server. This name should be the alias name if your server uses an alias.
  7. From the drop-down list, specify whether security should be enabled or disabled for the listen socket.
  8. Click OK.
  9. Click Restart Required. The Apply Changes page displays.
  10. Click the Restart Proxy Server button to apply the changes.

Editing Listen Sockets

To edit listen sockets
  1. Access the Server Manager and click the Preferences tab.
  2. Click the Edit Listen Sockets link. The Edit Listen Sockets page displays.
  3. In the Configured Sockets table, click the link for the listen socket you want to edit. The Edit Listen Sockets page displays.
  4. Make the desired changes to the following options:
  5. General
    • Listen Socket ID. The internal name for the listen socket. You cannot change this name after a listen socket has been created.
    • IP Address. The IP address of the listen socket. This can be in dotted-pair or IPv6 notation. Can also be 0.0.0.0, any, or ANY or INADDR_ANY (all IP addresses).
    • Port. The port number on which to create the listen socket. Legal values are 1-65535. On UNIX, creating sockets that listen on ports 1-1024 requires superuser privileges. Configure an SSL listen socket to listen on port 443.
    • Server Name. The default server for this listen socket.
  6. Security

If security is disabled, only the following parameter is displayed:

If security is enabled, the following parameters are displayed:

Deleting Listen Sockets

To delete listen sockets
  1. Access the Server Manager and click the Preferences tab.
  2. Click the Edit Listen Sockets link.
  3. Select the check box next to the listen socket you want to delete and click OK. You will be prompted to confirm deletion. It is possible to delete any listen socket, provided it is not the only listen socket for that instance.
  4. Click Restart Required. The Apply Changes page displays.
  5. Click the Restart Proxy Server button to apply the changes.

MIME Types

A Multi-purpose Internet Mail Extension (MIME) 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 page that lets you create new MIME types for use with your server. The proxy adds the new types to the mime.types file. For more information on blocking files based on MIME types, see Filtering by MIME Type.

This section contains the following topics:

Creating a New MIME Type

To create a MIME type
  1. Access the Server Manager, and click the Preferences tab.
  2. Click the Create/Edit MIME Types link. The Create/Edit MIME Types page displays showing all the MIME types listed in the proxy’s mime.types file.
  3. Specify the category of the MIME type from the drop-down list. 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. For more information on the category, see the online Help.
  4. Specify the content type that will appear in the HTTP header.
  5. Specify the file suffix. 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 should not map one file extension to two MIME types.
  6. Click the New button to add the MIME type.

Editing a MIME Type

To Edit a MIME type
  1. Access the Server Manager, and click the Preferences tab.
  2. Click the Create/Edit MIME Types link. The Create/Edit MIME Types page that displays shows all the MIME types listed in the proxy’s mime.types file.
  3. You can edit any MIME type by clicking the Edit link for that MIME type.
  4. Make the desired changes and click the Change MIME Type button.

Removing a MIME Type

To Remove a MIME type
  1. Access the Server Manager, and click the Preferences tab.
  2. Click the Create/Edit MIME Types link. The Create/Edit MIME Types page that displays shows all the MIME types listed in the proxy’s mime.types file.
  3. You can remove any MIME type by clicking the Remove link for that MIME type.

Administering Access Control

The Administer Access Control page allows you to manage access control lists (ACLs). ACLs allow you to control which clients can access your server. ACLs can screen out certain users, groups, or hosts to either allow or deny access to part of your server, and set up authentication so that only valid users and groups can access part of the server. For more information about access control, see Controlling Access to Your Server.

To manage access control lists
  1. Access the Server Manager, and click the Preferences tab.
  2. Click the Administer Access Control link. The Administer Access Control page displays.
  3. Pick a resource, an existing ACL, or type in the ACL name and click the Edit button. The Access Control Rules for page displays.
  4. Make the desired changes and click Submit. For more information about access control see "Setting Access Control for a Server Instance" in Controlling Access to Your Server.

Configuring the ACL Cache

The Configure ACL Cache page is used to enable or disable the proxy authentication cache, set the proxy authentication cache directory, configure the cache table size, and set the entry expiration time.

To configure the ACL Cache
  1. Access the Server Manager and click the Preferences tab.
  2. Click the Configure ACL Cache link. The Configure ACL Cache page displays.
  3. You can enable or disable the proxy authentication cache.
  4. Select the number of users in the user cache from the Proxy Auth User Cache Size drop-down list. The default size is 200.
  5. Select the number of group IDs that can be cached for a single UID/cache entry from the Proxy Auth Group Cache Size drop-down list. The default size is 4.
  6. Select the number of seconds before cache entries expire. Each time an entry in the cache is referenced, its age is calculated and checked against this value. The entry is not used if its age is greater than or equal to the Proxy Auth Cache Expiration value. If this value is set to 0, the cache is turned off.

    7. If you use a large number for this value, you may need to restart the Proxy Server when you make changes to the LDAP entries. For example, if this value is set to 120 seconds, the Proxy Server might be out of sync with the LDAP server for as long as 2 minutes. If your LDAP entries are not likely to change often, use a large number. The default expiration value is 2 minutes.

  7. Click OK.
  8. Click Restart Required. The Apply Changes page displays.
  9. Click the Restart Proxy Server button to apply the changes.

Understanding DNS Caching

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.

Configuring the DNS Cache

The Configure DNS Cache page is used to enable or disable DNS caching, set the size of the DNS cache, set the expiration of DNS cache entries, and enable or disable negative DNS caching.

To configure the DNS Cache
  1. Access the Server Manager and click the Preferences tab.
  2. Click the Configure DNS Cache link. The Configure DNS Cache page displays.
  3. You can enable or disable DNS caching.
  4. Select the number of entries from the DNS Cache Size drop-down list that can be stored in the DNS cache. The default size is 1024.
  5. You can set the DNS cache expiration time. The Proxy Server purges DNS cache entries from the cache when it reaches a pre-set expiration time. The default DNS expiration time is 20 minutes.
  6. You can enable or disable caching of errors when the host name is not found.
  7. Click OK.
  8. Click Restart Required. The Apply Changes page displays.
  9. Click the Restart Proxy Server button to apply the changes.

Configuring 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 cannot 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.example.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 four 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. Access the Server Manager and click the Preferences tab.
  2. Click the Configure DNS Subdomains link. The Configure DNS Subdomains page displays.
  3. Select a resource from the drop-down list or specify a regular expression.
  4. Select the number of levels from the Local Subdomain Depth drop-down list.
  5. Click OK.
  6. Click Restart Required. The Apply Changes page displays.
  7. Click the Restart Proxy Server button to apply the changes.

Configuring HTTP Keep-Alive

The Configure HTTP Client page is used to enable keep-alives on your proxy server.

The proxy supports HTTP keep-alive packets. The proxy, by default, doe s not use keep-alive connections, but for some systems, using the keep-alive feature can improve the proxy’s performance. 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.

To configure HTTP Keep-Alive
  1. Access the Server Manager and click the Preferences tab.
  2. Click the Configure HTTP Client link. The Configure HTTP Client page displays.
  3. Select a resource from the drop-down list. Select a HTTP or HTTPS resource to configure keep-alives on your Proxy Server or specify a regular expression.
  4. Specify whether the HTTP client should use persistent connections by clicking the appropriate Keep Alive option.
  5. Specify the maximum number of seconds in the Keep Alive Timeout field to keep a persistent connection open. The default value is 29.
  6. You can specify whether the HTTP client can reuse existing persistent connections for all types of requests by selecting the appropriate Persistent Connection Reuse option. The default value is off and does not allow persistent connections to be reused for non-GET requests nor for requests with a body.
  7. Specify the HTTP protocol version string in the HTTP Version String field. You should not specify this parameter unless you encounter specific protocol interoperability problems.
  8. Specify the Proxy Server product name and version in the Proxy Agent Header field.
  9. Specify the nickname of the client certificate in the SSL Client Certificate Nickname field to present to the remote server.
  10. Select the appropriate SSL Server Certificate Validation option to indicate whether the Proxy Server must validate the certificate presented by the remote server.
  11. Click OK.
  12. Click Restart Required. The Apply Changes page displays.
  13. Click the Restart Proxy Server button to apply the changes.


Previous      Contents      Index      Next     

Part No: 819-3650-10.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.