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:
This section describes how to start the Proxy Server on different platforms. Once the server is installed, it listens for and accepts requests.
Access the Server Manager and click the Preferences tab.
Click the Start/Stop Server link.
The Start/Stop Server page is displayed.
Click the On button.
The status of the server appears in the Start/Stop Server page.
You can start the Proxy Server on UNIX or Linux in either of the following ways:
From the command line, go to server-root/proxy-serverid and type ./start to start the Proxy Server.
Use start. If you want to use this script with init, you must include the start command prxy:2:respawn:server-root/proxy-serverid/start -start -i in /etc/inittab.
You can start the Proxy Server on Windows in any of the following ways
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.
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, doing so 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.
This section describes the various methods to stop the Proxy Server on different platforms.
Access the Server Manager and click the Preferences tab.
Click the Start/Stop Server link.
The Start/Stop Server page is displayed.
Click the Off button.
The status of the server appears in the Start/Stop Server page.
You can stop the Proxy Server on UNIX or Linux in either of the following ways:
From the command line, go to server-root/proxy-serverid and type ./stop.
If you used the etc/inittab file to restart the server you must remove the line starting the server from /etc/inittab and type kill -1 1 before you try to stop the server. Otherwise, the server restarts automatically after it is stopped.
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, a few seconds might lapse before the server completes its shut-down process and its status changes to Off.
If your system crashes or is taken offline, the server stops and any requests it was servicing might be lost.
If you have a security module installed with your server, you will be required to provide the appropriate passwords before starting or stopping the server.
You can stop the Proxy Server on Windows in any of the following ways:
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
This section describes the various methods to restart the Proxy Server on different platforms.
You can restart the server using one of the following methods:
Restarting the servers manually.
Automatically restart the server from the inittab file
If you are using a version of UNIX or Linux not derived from System V (such as SunOSTM 4.1.3), you will not be able to use the inittab file.
Automatically restart the server with daemons in /etc/rc2.d when the system reboots.
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.
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 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.
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.
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.
You can restart the server by using the Services Control Panel or by completing the following task.
Use Control Panel > Administrative Tools > Services >
Select Sun Java System Web Proxy Server 4.0 (proxy-serverid) from the list of services.
Change the Startup type to Automatic in the Properties window. Your system will start the server each time the computer starts or reboots.
Click OK.
When the server is off, it stops accepting new connections. Then the server waits for all outstanding connections to complete. The time the server waits before timing out is configurable in the magnus.conf file. By default, this value 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 might increase the time necessary for the server to shut down.
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 whether you have unsaved and unapplied changes. If you have unsaved changes, save the changes and restart the Proxy Server so it can begin using the new configurations.
The two types of server settings are 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, the View Server Settings 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 proxy-id/config subdirectory.
Access the Server Manager and click the Preferences tab.
Click the View Server Settings link.
The View Server Settings page is displayed.
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 enables you to go to a previous configuration if you are having trouble with your current configuration. For example, if you made 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.
Access the Server Manager and click the Preferences tab.
Click the Restore Configuration link.
The Restore Configuration page is displayed. 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.
Access the Server Manager and click the Preferences tab.
Click the Restore Configuration link.
The Restore Configuration page is displayed. 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 in the left column of the table. time is the date and time to which you want to restore.
Access the Server Manager and click the Preferences tab.
Click the Restore Configuration link.
The Restore Configuration page is displayed.
In the Set Number Of Sets Of Backups field, type the number of backups you want to display.
Click the Change button.
The Configure System Preferences page enables you to set up or change the basic aspects of your server. The page allows you to do the following:
Change the server user, the number of processes, listen queue size, proxy timeout, and timeout after interrupt for your proxy server
Enable DNS, ICP, proxy arrays, and parent arrays
The preference options are:
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 member 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.
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.
Access the Server Manager and click the Preferences tab.
Click the Configure System Preferences link.
The Configure System Preferences page is displayed.
Change the options, and then click OK.
Click Restart Required.
The Apply Changes page is displayed.
Click the Restart Proxy Server button to apply the changes.
The Tune Proxy page enables you to change the default parameters to tune your proxy server’s performance.
Access the Server Manager and click the Preferences tab.
Click the Tune Proxy link.
The Tune Proxy page is displayed.
(Optional) Modify the width of FTP listings to allow longer file names and thus reduce file name truncation.
The default width is 80 characters.
Click OK.
Click Restart Required.
The Apply Changes page id displayed.
Click the Restart Proxy Server button to apply the changes.
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.
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 address can be in dotted-pair or IPv6 notation. It 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. The values allowed 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:
Security. Enables or disables security for the listen socket selected.
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 setting is Optional by default.
SSL Version 2. Enables or disables SSL Version 2. This setting is disabled by default.
SSL Version 2 Ciphers. Lists all ciphers within this suite. Select the ciphers that you want to enable for the listen socket you are editing by selecting or deselecting the boxes. The default versions are deselected.
SSL Version 3. Enables or disables SSL Version 3. This setting 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 selecting or deselecting the boxes. The default versions are selected.
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. The values are 1-1024.
Protocol Family. The socket family type. The values allowed are inet, inet6, and nca. Use the value inet6 for IPv6 listen sockets. Specify nca to make use of the Solaris Network Cache and Accelerator.
Listen sockets are added, edited, and deleted using the Server Manager’s Add Listen Socket and Edit Listen Sockets pages.
Security for a listen socket has Enabled as an option only after the required certificates have been installed and until then only Disabled shows up in the drop-down box.
This section contains the following topics:
To Configure the Content Server-Authenticates-Proxy Scenario
To Configure the Proxy-Authenticates-Client and Content Server-Authenticates-Proxy scenario
Access the Server Manager and click the Preferences tab.
Click the Add Listen Socket link.
The Add Listen Socket page is displayed.
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.
The IP address can be in dotted-pair or IPv6 notation. It 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. The values allowed 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 setting 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 is displayed.
Click the Restart Proxy Server button to apply the changes.
Access the Server Manager and click the Preferences tab.
Click the Edit Listen Sockets link.
The Edit Listen Sockets page is displayed.
In the Configured Sockets table, click the link for the listen socket you want to edit.
The Edit Listen Sockets page is displayed.
Make the desired changes to the options.
For a description of the options, see the beginning of this section.
Click OK.
Click Restart Required.
The Apply Changes page is displayed.
Click the Restart Proxy Server button to apply the changes.
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 is displayed.
Click the Restart Proxy Server button to apply the changes.
The Select Directory Services page lists all directory services for the specified proxy server instance. The page allows you to select the directory services to use with a specific proxy server instance. For more information, see Configuring Directory Services.
Access the Server Manager, and click the Preferences tab.
Click the Select Directory Services link.
The Select Directory Services page is displayed showing all the directory services for the specified proxy server instance.
Select a directory service from the list.
Click OK.
Click Restart Required.
The Apply Changes page is displayed.
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 describes how to create, edit, or remove 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 is displayed 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. 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.
Access the Server Manager, and click the Preferences tab.
Click the Create/Edit MIME Types link.
The Create/Edit MIME Types page that appears shows all the MIME types listed in the proxy’s mime.types file.
Click the Edit link for the MIME type you want to edit.
Make the desired changes. Click the Change MIME Type button.
Access the Server Manager, and click the Preferences tab.
Click the Create/Edit MIME Types link.
The Create/Edit MIME Types page that appears shows all the MIME types listed in the proxy’s mime.types file.
Click the Remove link for the MIME type you want to remove.
The Administer Access Control page enables you to manage access control lists (ACLs). ACLs enable 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. ACLs can also set up authentication so that only valid users and groups can access part of the server. For more information about access control, see Chapter 8, Controlling Access to Your Server.
Access the Server Manager, and click the Preferences tab.
Click the Administer Access Control link.
The Administer Access Control page is displayed.
Select a resource, or an existing ACL, or type the ACL name and click the Edit button.
The Access Control Rules for page is displayed.
Make the desired changes and click Submit.
For more information about access control see “Setting Access Control for a Server Instance” in Chapter 8, Controlling Access to Your Server.
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.
Access the Server Manager and click the Preferences tab.
Click the Configure ACL Cache link.
The Configure ACL Cache page is displayed.
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 is displayed.
Click the Restart Proxy Server button to apply the changes.
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.
There are two types of proxy DNS cache:
host-dns-cache-init: Enables caching of the remote hosts' host-to-ip lookups.
ip-dns-cache-init: Enables caching of the clients' ip-to-host lookups.
From Web Proxy Server 4.0.10, you can configure statistics and profiling to view statistics of either the clients' ip-to-host cache or the remote servers' host-to-ip 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.
Access the Server Manager and click the Preferences tab.
Click the Configure DNS Cache link.
The Configure DNS Cache page is displayed.
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.
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.
Enable or disable caching of errors when the host name is not found.
Click OK.
Click Restart Required.
The Apply Changes page is displayed.
Click the Restart Proxy Server button to apply the changes.
Some URLs contain host names with many levels of subdomains. The proxy server might take 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, the proxy could take a long time 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.
Access the Server Manager and click the Preferences tab.
Click the Configure DNS Subdomains link.
The Configure DNS Subdomains page is displayed.
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 is displayed.
Click the Restart Proxy Server button to apply the changes.
The Configure HTTP Client page is used to enable keep-alives on your 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. The proxy, by default, does not use keep-alive connections, but for some systems, using the keep-alive feature can improve the proxy’s performance.
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. Re-establishing connections is time consuming. Therefore, keep-alive packets can be useful.
Access the Server Manager and click the Preferences tab.
Click the Configure HTTP Client link.
The Configure HTTP Client page is displayed.
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 selecting 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.
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, which 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.
Do 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 is displayed.
Click the Restart Proxy Server button to apply the changes.