Sun Java System Web Proxy Server 4.0.1 Administration Guide |
Chapter 7
Configuring Server PreferencesThis 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 ServerThis 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
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
- Use Start > Programs > Sun Microsystems > Sun Java System Web Proxy Server version > Start Proxy Server
- Use Control Panel > Administrative Tools > Services > Sun Java System Web Proxy Server 4.0 (proxy-serverid) > Start
- From a command prompt, go to server_root\proxy-serverid and type startsvr.bat to start the Proxy Server.
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.
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
- Using a text editor, open the start file.
- Locate the -start line in the script and insert the following:
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 ServerThis section describes the various methods to stop the Proxy Server on different platforms.
To stop the Proxy Server from the administration interface
The status of the server appears in the Start/Stop Server page.
To stop the Proxy Server on UNIX or Linux
- From the command line, go to server_root/proxy-serverid and type ./stop.
- Use stop, which shuts down the server completely, interrupting service until it is restarted. If you set the etc/inittab file to automatically restart (using respawn), you must remove the line pertaining to the proxy server in etc/inittab before shutting down the server; otherwise, the server automatically restarts.
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
- Use Start > Programs > Sun Microsystems > Sun Java System Web Proxy Server version > Stop Proxy Server
- From a command prompt, go to server_root\proxy-serverid and type stopsvr.bat to stop the Proxy Server.
- Use the Sun Java System Proxy Server 4.0 (proxy-serverid) service in the Services window: Control Panel > Administrative Tools > Services
Restarting the Proxy ServerThis 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
- 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.
- At the command-line prompt, type the following line and press Enter:
server_root/proxy-serverid/restart
where server_root is the directory where you installed the server.
- 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
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 SettingsDuring 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
Viewing and Restoring Backups of Configuration FilesYou 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
- Access the Server Manager and click the Preferences tab.
- Click the Restore Configuration link. The Restore Configuration page displays. The page lists all the previous configurations ordered by date and time.
- 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
- Access the Server Manager and click the Preferences tab.
- Click the Restore Configuration link. The Restore Configuration page displays. The page lists all the previous configurations ordered by date and time.
- Click the Restore link 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 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
Configuring System PreferencesThe 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
- Access the Server Manager and click the Preferences tab.
- Click the Configure System Preferences link. The Configure System Preferences page displays.
- Change the options as required, and then click OK.
- Click Restart Required. The Apply Changes page displays.
- 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.
Tuning the Proxy ServerThe Tune Proxy page allows you to change the default parameters to tune your proxy server’s performance.
To change the default tuning parameters
- Access the Server Manager and click the Preferences tab.
- Click the Tune Proxy link. The Tune Proxy page displays.
- 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.
- Click OK.
- Click Restart Required. The Apply Changes page displays.
- Click the Restart Proxy Server button to apply the changes.
Adding and Editing Listen SocketsBefore 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
- Access the Server Manager and click the Preferences tab.
- Click the Add Listen Socket link. The Add Listen Socket page displays.
- Specify the internal name for the listen socket. You cannot change this name after the listen socket has been created.
- 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).
- 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.
- 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.
- From the drop-down list, specify whether security should be enabled or disabled for the listen socket.
- Click OK.
- Click Restart Required. The Apply Changes page displays.
- Click the Restart Proxy Server button to apply the changes.
Editing Listen Sockets
To edit listen sockets
- Access the Server Manager and click the Preferences tab.
- Click the Edit Listen Sockets link. The Edit Listen Sockets page displays.
- In the Configured Sockets table, click the link for the listen socket you want to edit. The Edit Listen Sockets page displays.
- Make the desired changes to the following options:
- 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.
- Security
If security is disabled, only the following parameter is displayed:
If security is enabled, the following parameters are displayed:
- Security. Enables or disables security for the listen socket selected.
- Server Certificate Name. Select an installed certificate from the drop-down list to use for this listen socket.
- Client Authentication. Specifies whether client authentication is required on this listen socket. This is Optional by default.
- SSL Version 2. Enables or disables SSL Version 2. This is disabled by default.
- SSL Version 2 Ciphers. Lists all ciphers within this suite. Select the ciphers you want to enable for the listen socket you are editing by checking or unchecking the boxes. The default versions will be unchecked.
- SSL Version 3. Enables or disables SSL Version 3. This is enabled by default.
- TLS. Enables or disables TLS, the Transport Layer Security protocol for encrypted communication. This is enabled by default.
- TLS Rollback. Enables or disables TLS Rollback. Note that disabling TLS Rollback leaves connections vulnerable to version rollback attacks. This is enabled by default.
- SSL Version 3 and TLS Ciphers. Lists all ciphers within this suite. Select the ciphers you want to enable for the listen socket you are editing by checking or unchecking the boxes. The default versions will be checked.
- Advanced
- Number Of Acceptor Threads. The number of acceptor threads for the listen socket. The recommended value is the number of processors in the machine. The default is 1, legal values are 1-1024.
Protocol Family. The socket family type. Legal values are inet, inet6, and nca. Use the value inet6 for IPv6 listen sockets. Specify nca to make use of the SolarisTM Network Cache and Accelerator.
- Click OK.
- Click Restart Required. The Apply Changes page displays.
- Click the Restart Proxy Server button to apply the changes.
Deleting Listen Sockets
To delete listen sockets
- Access the Server Manager and click the Preferences tab.
- Click the Edit Listen Sockets link.
- 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.
- Click Restart Required. The Apply Changes page displays.
- Click the Restart Proxy Server button to apply the changes.
MIME TypesA 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
- Access the Server Manager, and click the Preferences tab.
- 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.
- 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.
- Specify the content type that will appear in the HTTP header.
- 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.
- Click the New button to add the MIME type.
Editing a MIME Type
To Edit a MIME type
- Access the Server Manager, and click the Preferences tab.
- 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.
- You can edit any MIME type by clicking the Edit link for that MIME type.
- Make the desired changes and click the Change MIME Type button.
Removing a MIME Type
To Remove a MIME type
Administering Access ControlThe 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
- Access the Server Manager, and click the Preferences tab.
- Click the Administer Access Control link. The Administer Access Control page displays.
- Pick a resource, an existing ACL, or type in the ACL name and click the Edit button. The Access Control Rules for page displays.
- 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 CacheThe 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
- Access the Server Manager and click the Preferences tab.
- Click the Configure ACL Cache link. The Configure ACL Cache page displays.
- You can enable or disable the proxy authentication cache.
- Select the number of users in the user cache from the Proxy Auth User Cache Size drop-down list. The default size is 200.
- 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.
- 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.
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.
- Click OK.
- Click Restart Required. The Apply Changes page displays.
- Click the Restart Proxy Server button to apply the changes.
Understanding DNS CachingProxy 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
- Access the Server Manager and click the Preferences tab.
- Click the Configure DNS Cache link. The Configure DNS Cache page displays.
- You can enable or disable DNS caching.
- 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.
- 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.
- You can enable or disable caching of errors when the host name is not found.
- Click OK.
- Click Restart Required. The Apply Changes page displays.
- Click the Restart Proxy Server button to apply the changes.
Configuring DNS SubdomainsSome 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
- Access the Server Manager and click the Preferences tab.
- Click the Configure DNS Subdomains link. The Configure DNS Subdomains page displays.
- Select a resource from the drop-down list or specify a regular expression.
- Select the number of levels from the Local Subdomain Depth drop-down list.
- Click OK.
- Click Restart Required. The Apply Changes page displays.
- Click the Restart Proxy Server button to apply the changes.
Configuring HTTP Keep-AliveThe 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
- Access the Server Manager and click the Preferences tab.
- Click the Configure HTTP Client link. The Configure HTTP Client page displays.
- 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.
- Specify whether the HTTP client should use persistent connections by clicking the appropriate Keep Alive option.
- Specify the maximum number of seconds in the Keep Alive Timeout field to keep a persistent connection open. The default value is 29.
- 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.
- 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.
- Specify the Proxy Server product name and version in the Proxy Agent Header field.
- Specify the nickname of the client certificate in the SSL Client Certificate Nickname field to present to the remote server.
- Select the appropriate SSL Server Certificate Validation option to indicate whether the Proxy Server must validate the certificate presented by the remote server.
- Click OK.
- Click Restart Required. The Apply Changes page displays.
- Click the Restart Proxy Server button to apply the changes.