Sun Java System Web Proxy Server 4.0.11 Administration Guide

Chapter 11 Proxying and Routing URLs

This chapter describes how requests are handled by the proxy server. It also explains how to enable proxying for specific resources. The chapter also covers how to configure the proxy server to route URLs to different URLs or servers.

This chapter contains the following sections:

Enabling/Disabling Proxying for a Resource

You can turn proxying on or off for resources. Resources can be individual URLs, groups of URLs with something in common, or an entire protocol. You can control whether proxying is on for the entire server, for various resources, or for resources as specified in a template file. You can deny access to one or more URLs by turning off proxying for that resource. This setting can be a global way to deny or allow all access to a resource. You can also allow or deny access to resources by using URL filters. For more information about URL filters, see Filtering URLs.

ProcedureTo Enable Proxying for a Resource

  1. Access the Server Manager and click the Routing tab.

  2. Click the Enable/Disable Proxying link.

    The Enable/Disable Proxying page is displayed.

  3. Select the resource from the drop-down list or click the Regular Expression button, type a regular expression and click OK.

  4. You can choose a default setting for the resource you specified.

    • Use Default Setting Derived From A More General Resource. The settings for a more general resource that includes this one will be used for this resource.

    • Do Not Proxy This Resource. This resource cannot be reached through the proxy.

    • Enable Proxying Of This Resource. The proxy allows clients to access this resource (provided they pass the other security and authorization checks). When you enable proxying for a resource, all methods are enabled. The read methods, including GET, HEAD, INDEX, POST, and CONNECT for SSL tunneling, and the write methods, including PUT, MKDIR, RMDIR, MOVE, and DELETE, are all enabled for that resource. Barring any other security checks, clients all have read and write access.

  5. Click OK.

  6. Click Restart Required.

    The Apply Changes page is displayed.

  7. Click the Restart Proxy Server button to apply the changes.

Routing Through Another Proxy

The Set Routing Preferences page is used to configure your proxy server to route certain resources using the derived default configuration or direct connections; or using proxy arrays, ICP neighborhood, another proxy server, or a SOCKS server.

Configuring Routing for a Resource

ProcedureTo Configure Routing for a Resource

  1. Access the Server Manager and click the Routing tab.

  2. Click the Set Routing Preferences link.

    The Set Routing Preferences page is displayed.

  3. Select the resource from the drop-down list or click the Regular Expression button, type a regular expression, and clicking OK.

  4. Select the the type of routing you would like for the resource you are configuring.

    The available options are::

    • Derived Default Configuration. The proxy server uses a more general template, that is, one with a shorter, matching regular expression, to determine whether it should use the remote server or another proxy. For example, if the proxy routes all http://.* requests to another proxy server and all http://www.* requests to the remote server, you could create a derived default configuration routing for http://www.example.* requests, that would go directly to the remote server because of the setting for the http://www.* template.

    • Direct Connections. The request will always go directly to the remote server instead of through the proxy.

    • Route Through A SOCKS Server. The requests for the specified resource will be routed through a SOCKS server. If you choose this option, specify the name or IP address and the port number of the SOCKS server that the proxy server will route through.

    • Route Through. Enables you to specify whether you would like to route through a proxy array, ICP neighborhood, parent array, or proxy server. If you choose multiple routing methods, the proxy will follow the hierarchy shown on the form: proxy array, redirect, ICP, parent array, or another proxy. For more information on routing through a proxy server, see Chaining Proxy Servers.

      For information on routing through a SOCKS server, see Routing Through a SOCKS Server. For information on routing through proxy arrays, parent arrays, or ICP neighborhoods, see Chapter 12, Caching.


    Note –

    To enable routing of connect requests on ports other than 443, change the ppath parameter to connect://.* in the obj.conf file.


  5. Click OK.

  6. Click Restart Required.

    The Apply Changes page is displayed.

  7. Click the Restart Proxy Server button to apply the changes.

Chaining Proxy Servers

You can have the proxy access another proxy for some resources instead of accessing the remote server. Chaining is a good way to organize several proxies behind a firewall. Chaining also enables you to build hierarchical caching.

ProcedureTo Route Through Another Proxy Server

  1. Access the Server Manager and click the Routing tab.

  2. Click the Set Routing Preferences link.

    The Set Routing Preferences page is displayed.

  3. Select the resource from the drop-down list or click the Regular Expression button, type a regular expression and click OK.

  4. Select the Route Through option in the Routing Through Another Proxy section of the page.

  5. Select the Another Proxy checkbox.

  6. In the Another Proxy field, you can type the server name and the port number of the proxy sever that you want to route through.

    Type the server name and port number as servername:port

  7. Click OK.

  8. Click Restart Required.

    The Apply Changes page is displayed.

  9. Click the Restart Proxy Server button to apply the changes.

Routing Through a SOCKS Server

If you already have a remote SOCKS server running on your network, you can configure the proxy to connect to the SOCKS server for specific resources.

ProcedureTo Route Through a SOCKS server

  1. Access the Server Manager and click the Routing tab.

  2. Click the Set Routing Preferences link.

    The Set Routing Preferences page is displayed.

  3. Select the resource from the drop-down list or click the Regular Expression button, type a regular expression and click OK.

  4. Select the Route Through option in the Routing Through Another Proxy section of the page.

  5. Select the Route Through SOCKS Server option.

  6. Specify the name or IP address and the port number of the SOCKS server that the proxy server will route through.

  7. Click OK.

  8. Click Restart Required.

    The Apply Changes page is displayed.

  9. Click the Restart Proxy Server button to apply the changes.

Next Steps

Once you have enabled routing through a SOCKS server, you should create proxy routes using the SOCKS v5 Routing page. Proxy routes identify the IP addresses that are accessible through the SOCKS server your proxy routes through. Proxy routes also specify whether that SOCKS server connects directly to the host.

Forwarding the Client IP Address to the Server

The Forward Client Credentials page is used to configure the proxy to send client credentials to the remote server.

ProcedureTo Configure the Proxy to Send Client IP Addresses

  1. Access the Server Manager and click the Routing tab.

  2. Click the Forward Client Credentials link.

    The Forward Client Credentials page is displayed.

  3. Select the resource from the drop-down list or click the Regular Expression button, type a regular expression and click OK.

  4. Set the forwarding options:

    • Client IP Addressing Forwarding. The Proxy Server does not send the client’s IP address to remote servers when making requests for documents. Instead, the proxy acts as the client and sends its IP address to the remote server. However, you might want to pass on the client’s IP address in the following situations:

      • If your proxy is one in a chain of internal proxies.

      • If your clients need to access servers that depend on knowing the client’s IP address. You can use templates to send the client’s IP address only to particular servers.

      Set the option to configure the proxy to send client IP addresses:

      • Default. Enables the Proxy Server to forward the client’s IP addresses.

      • Blocked. Does not allow the proxy to forward the client’s IP addresses.

      • Enabled Using HTTP Header. You can specify an HTTP header for the proxy to use when forwarding IP addresses. The default HTTP header is named Client-ip, but you can send the IP address in any header you choose.

    • Client Proxy Authentication Forwarding. Set the option to configure the proxy to send the client’s authentication details:

      • Default. Enables the Proxy Server to forward the client’s authentication details.

      • Blocked. Does not allow the proxy to forward the client’s authentication details.

      • Enabled Using HTTP Header. You can specify an HTTP header for the proxy to use when forwarding authentication details.

    • Client Cipher Forwarding. Set the option to configure the proxy to send the name of the client’s SSL/TLS cipher suite to remote servers.

      • Default. Enables the Proxy Server to forward the name of the client’s SSL/TLS cipher suite to remote servers.

      • Blocked. Does not allow the proxy to forward the name of the client’s SSL/TLS cipher suite to remote servers.

      • Enabled Using HTTP Header. You can specify an HTTP header for the proxy to use when forwarding the name of the client’s SSL/TLS cipher suite to remote servers. The default HTTP header is named Proxy-cipher, but you can send the name of the client’s SSL/TLS cipher suite in any header you choose.

    • Client Keysize Forwarding. Set the option to configure the proxy to send the size of the client’s SSL/TLS key to remote servers.

      • Default. Enables the Proxy Server to forward the size of the client’s SSL/TLS key to remote servers.

      • Blocked. Does not allow the proxy to forward the size of the client’s SSL/TLS key to remote servers.

      • Enabled Using HTTP Header. You can specify an HTTP header for the proxy to use when forwarding the size of the client’s SSL/TLS key to remote servers. The default HTTP header is named Proxy-keysize, but you can send the size of the client’s SSL/TLS key in any header you choose.

    • Client Secret Keysize Forwarding. Set the option to configure the proxy to send the size of the client’s SSL/TLS secret key to remote servers:

      • Default. Enables the Proxy Server to forward the size of the client’s SSL/TLS secret key to remote servers.

      • Blocked. Does not allow the proxy to forward the size of the client’s SSL/TLS secret key to remote servers.

      • Enabled Using HTTP Header. You can specify an HTTP header for the proxy to use when forwarding the size of the client’s SSL/TLS secret key to remote servers. The default HTTP header is named Proxy-secret-keysize, but you can send the size of the client’s SSL/TLS secret key in any header you choose.

    • Client SSL Session ID Forwarding. Set the option to configure the proxy to send the client’s SSL/TLS session ID to remote servers.

      • Default. Enables the Proxy Server to forward the client’s SSL/TLS session ID to remote servers.

      • Blocked. Does not allow the proxy to forward the client’s SSL/TLS session ID to remote servers.

      • Enabled Using HTTP Header. You can specify an HTTP header for the proxy to use when forwarding the client’s SSL/TLS session ID to remote servers. The default HTTP header is named Proxy-ssl-id, but you can send the client’s SSL/TLS session ID in any header you choose.

    • Client Issuer DN Forwarding. Set the option to configure the proxy to send the distinguished name of the issuer of the client’s SSL/TLS certificate to remote servers.

      • Default. Enables the Proxy Server to forward the distinguished name of the issuer of the client’s SSL/TLS certificate to remote servers.

      • Blocked. Does not allow the proxy to forward the distinguished name of the issuer of the client’s SSL/TLS certificate to remote servers.

      • Enabled Using HTTP Header. You can specify an HTTP header for the proxy to use when forwarding the distinguished name of the issuer of the client’s SSL/TLS certificate to remote servers. The default HTTP header is named Proxy-issuer-dn, but you can send the name of the issuer of the client’s SSL/TLS certificate in any header you choose.

    • Client User DN Forwarding. Set the option to configure the proxy to send the distinguished name of the subject of the client’s SSL/TLS certificate to remote servers.

      • Default. Enables the Proxy Server to forward the distinguished name of the subject of the client’s SSL/TLS certificate to remote servers.

      • Blocked. Does not allow the proxy to forward the distinguished name of the subject of the client’s SSL/TLS certificate to remote servers.

      • Enabled Using HTTP Header. You can specify an HTTP header for the proxy to use when forwarding the distinguished name of the subject of the client’s SSL/TLS certificate to remote servers. The default HTTP header is named Proxy-user-dn, but you can send the name of the subject of the client’s SSL/TLS certificate in any header you choose.

    • Client SSL/TLS Certificate Forwarding. Set the option to configure the proxy to send the client’s SSL/TLS certificate to remote servers.

      • Default. Enables the Proxy Server to forward the client’s SSL/TLS certificate to remote servers.

      • Blocked. Does not allow the proxy to forward the client’s SSL/TLS certificate to remote servers.

      • Enabled Using HTTP Header. You can specify an HTTP header for the proxy to use when forwarding the client’s SSL/TLS certificate to remote servers. The default HTTP header is named Proxy-auth-cert, but you can send the client’s SSL/TLS certificate in any header you choose.

    • Client Cache Information Forwarding. Select one of the options to configure the proxy to send information about local cache hits to remote servers:

      • Default. Enables the Proxy Server to forward the information about local cache hits to remote servers.

      • Blocked. Does not allow the proxy to forward the information about local cache hits to remote servers.

      • Enabled Using HTTP Header. You can specify an HTTP header for the proxy to use when forwarding information about local cache hits to remote servers. The default HTTP header is named Cache-info, but you can send the information about local cache hits in any header you choose.

    • Set Basic Authentication Credentials. Set the option to configure the proxy to send a HTTP request.

      • User. Specify the user to authenticate.

      • Password. Specify the user’s password.

      • Using HTTP Header. You can specify an HTTP header for the proxy to use to communicate the credentials.

  5. Click OK.

  6. Click Restart Required. The Apply Changes page is displayed.

  7. Click the Restart Proxy Server button to apply the changes.

Allowing Clients to Check IP Address

To maintain your network’s security, your client might have a feature that restricts access to only certain IP addresses. To allow your clients to use this feature, the Proxy Server provides support for checking Java IP Address.

Checking Java IP Address allows clients to query the Proxy Server for the IP address used to reroute a resource. Because DNS spoofing often occurs with Java Applets, this feature enables clients to see the true IP address of the origin server.

When this feature is enabled, the Proxy Server attaches a header containing the IP address that was used for connecting to the destination origin server. For example. if this feature is enabled, and if the request contains a "Pragma: dest-ip" header, the Proxy Server includes the IP address of the origin server as the value of a "Dest-ip:" header.

For information about the Server Application Function (SAF) used for checking Java IP Address, see java-ip-check in the section ObjectType in Sun Java System Web Proxy Server 4.0.11 Configuration File Reference

ProcedureTo Check the Java IP Address

  1. Access the Server Manager and click the Routing tab.

  2. Click the Check Java IP Address link.

    The Check Java IP Address page is displayed.

  3. Select the resource from the drop-down list or click the Regular Expression button, type a regular expression and click OK.

  4. Enable, disable or use the default configuration for Java IP address checking.


    Note –

    The default option uses a derived default configuration from a more general template. The general template has a shorter, matching regular expression to determine whether Java IP address checking should be enabled or disabled.


  5. Click OK.

  6. Click Restart Required.

    The Apply Changes page is displayed.

  7. Click the Restart Proxy Server button to apply the changes.

Client Autoconfiguration

If your proxy server supports many clients, you might want to use a client autoconfiguration file to configure all of your browser clients. The autoconfiguration file contains a JavaScriptTM function that determines which proxy, if any, the browser uses when accessing various URLs. For more information on this feature, see Chapter 17, Using the Client Autoconfiguration File.

Setting the Network Connectivity Mode

You can connect or disconnect the proxy server computer from the network. This feature means you can easily install the proxy on a portable computer that you can use for demonstrations.

When the proxy is disconnected from the network, documents are returned directly from the cache. The proxy can’t do up-to-date checks, so the documents are retrieved very quickly. However, the documents might not be up to date. See Chapter 12, Caching for more information on caching).

If you are not connected to a network, connections never hang because the proxy server is aware that no network connection exists and never tries to connect to a remote server. You can use this no-network setting when the network is down but the proxy server computer is running. Running the proxy disconnected from the network means that you will eventually be accessing stale data from the cache. Also, running without the network makes the proxy security features unnecessary.

Proxy Server offers four network connectivity modes:

ProcedureTo Change the Running Mode for the Proxy Server

  1. Access the Server Manager and click the Routing tab.

  2. Click the Set Connectivity Mode link. The Set Connectivity Mode page is displayed.

  3. Select the resource from the drop-down list or click the Regular Expression button, type a regular expression and click OK.

  4. Select the mode you want.

  5. Click OK.

  6. Click Restart Required. The Apply Changes page is displayed.

  7. Click the Restart Proxy Server button to apply the changes.

Changing the Default FTP Transfer Mode

FTP has two different ways to establish a data connection between the FTP server and the client, the proxy acting as a client. The two modes are referred to as PASV and PORT mode FTP.

Some FTP sites run a firewall, which makes PASV mode non-functional for proxy servers. Therefore, the proxy server can be configured to use the PORT mode FTP. You can turn on PORT mode for the entire server, or you can turn it on only for specific FTP servers.

Even when PASV mode is on, the proxy server will use PORT mode if the remote FTP server does not support PASV mode.

If the proxy server is behind a firewall that makes the PORT mode FTP non-functional, you cannot enable PORT mode. If default is selected for the resource, the proxy server uses the mode from a more general resource. If none is specified, PASV mode will be used.

ProcedureTo Set the FTP Mode

  1. Access the Server Manager and click the Routing tab.

  2. Click the Set FTP Mode link. The Set FTP Mode page is displayed.

  3. Select the resource from the drop-down list or click the Regular Expression button, type a regular expression and click OK.

  4. Select the FTP transfer mode

  5. Click OK.

  6. Click Restart Required. The Apply Changes page is displayed.

  7. Click the Restart Proxy Server button to apply the changes.

Specifying the SOCKS Name Server IP Address

If your proxy is configured to make its outbound connections through a SOCKS server, you might need to explicitly specify the IP address for the name server to be used with SOCKS.

You should specify the name server IP address if you are resolving outside host names with a DNS server other than an internal DNS service that is inside the firewall.

ProcedureTo Specify the SOCKS Name Server IP Address

  1. Access the Server Manager and click the Routing tab.

  2. Click the Set SOCKS Name Server link.

    The Set SOCKS Name Server page is displayed.

  3. Type the IP address of the DNS name server in the field.

  4. Click OK.


    Note –

    The feature that enables you to specify the SOCKS name server IP address at one time was only accessible through the SOCKS_NS environment variable. If you set the environment variable and use the SOCKS Name Server Setting form to specify the name server IP address, the proxy will use the IP address specified on the form instead of the environment variable.


  5. Click Restart Required.

    The Apply Changes page is displayed.

  6. Click the Restart Proxy Server button to apply the changes.

Configuring HTTP Request Load Balancing

The Configure HTTP Request Load Balancing page is used to distribute the load among the specified origin server.

ProcedureTo Configure HTTP Request Load Balancing

  1. Access the Server Manager and click the Routing tab.

  2. Click the Configure HTTP Request Load Balancing link.

    The Configure HTTP Request Load Balancing page is displayed.

  3. Select the resource from the drop-down list or click the Regular Expression button, type a regular expression and click OK.

  4. Specify the URL of an origin server in the Server field. If multiple server parameters are given, the Proxy Server will distribute the load among the specified origin server.

  5. In the Sticky Cookie field, specify the name of the cookie that when present in a response will cause subsequent requests to stick to that origin server. The default value is JSESSIONID.

  6. In the Sticky Parameter field, specify the name of a URI parameter to inspect for route information. When the URI parameter is present in a request URI and its value contains a colon, followed by a route ID, the request will “stick” to the origin server identified by that route ID. The default value is jsessionid.

  7. In the Route Header field, specify the name of the HTTP request header that is used to communicate route IDs to origin servers. The default value is proxy-jroute.

  8. In the Route Cookie field, specify the name of the cookie that is generated by the Proxy Server when it encounters a sticky cookie in a response.

    The default value is JROUTE.

  9. Set the Rewrite Host option to indicate whether the Host HTTP request header is rewritten to match the host specified by the server parameter.

  10. Set the Rewrite Location option to indicate whether Location HTTP response headers that match the server parameter should be rewritten.

  11. Set the Rewrite Content Location option to indicate whether Content-location HTTP response headers that match the server parameter should be rewritten.

  12. Indicate whether the headername HTTP response headers that match the server parameter should be rewritten, where headername is a user-defined header name. Specify the headername in the Headername field.

  13. Click OK.

  14. Click Restart Required.

    The Apply Changes page is displayed.

  15. Click the Restart Proxy Server button to apply the changes.

Managing URLs and URL Mappings

Use the Server Manager to map URLs to another server, sometimes called a mirror server. When a client accesses the proxy with a mirrored URL, the proxy retrieves the requested document from the mirrored server and not from the server specified in the URL. The client is never aware that the request is going to a different server. You can also redirect URLs. In this case, the proxy returns only the redirected URL to the client and not the document, so the client can then request the new document. Mapping also enables you to map URLs to a file, as in PAC and PAT mappings.

Creating and Modifying URL Mappings

To map a URL, you specify a URL prefix and where to map it. The following sections describe the various types of URL mappings. You can create the following types of URL mappings:

Clients accessing a URL are sent to a different location on the same server or on a different server. This feature is useful when a resource has moved or when you need to maintain the integrity of relative links when directories are accessed without a trailing slash.

For example, suppose you have a heavily loaded web server called hi.load.com that you want mirrored to another server called mirror.load.com. For URLs that go to the hi.load.com computer, you can configure the proxy server to use the mirror.load.com computer.

The source URL prefix must be unescaped, but in the destination (mirror) URL, only characters that are illegal in HTTP requests need to be escaped.

Do not use trailing slashes in the prefixes!

ProcedureTo create a URL mapping

  1. Access the Server Manager and click the URLs tab.

  2. Click the Create Mapping link.

    The Create Mapping page is displayed.

  3. Choose the type of mapping you want to create.

    • Regular Mappings. If you select this option, the following option is displayed in the lower section of the page:

      • Rewrite Host. Indicate whether the Host HTTP header is rewritten to match the host specified by the to parameter.

      • Reverse Mappings. Maps a redirected URL prefix to another URL prefix. If you select this option, the following option is displayed in the lower section of the page:

        • Rewrite Location. Indicate whether the Location HTTP response header should be rewritten.

        • Rewrite Content Location. Indicate whether the Content-location HTTP response header should be rewritten.

        • Rewrite Headername. Select the check box to indicate whether the headername HTTP response header should be rewritten, where headername is a user-defined header name.

        Regular Expressions. Map all URLs matching the expression to a single URL. For more information on regular expressions, see Chapter 16, Managing Templates and Resources.

      • Client Autoconfiguration. Maps URLs to a specific .pac file stored on the Proxy Server. For more information on autoconfiguration files, see Chapter 17, Using the Client Autoconfiguration File.

      • Proxy Array Table (PAT). Maps URLs to a specific .pat file stored on the Proxy Server. You should only create this type of mapping from a master proxy. For more information on PAT files and proxy arrays, see “Routing through Proxy Arrays” in Chapter 12, Caching

  4. Type the map source prefix.

    For regular and reverse mappings, this prefix should be the part of the URL you want to substitute.

    For regular expression mappings, the URL prefix should be a regular expression for all the URLs you want to match. If you also choose a template for the mapping, the regular expression will work only for the URLs within the template’s regular expression.

    For client autoconfiguration mappings and proxy array table mappings, the URL prefix should be the full URL that the client accesses.

  5. Type a map destination.

    For all mapping types except client autoconfiguration and proxy array table, this declaration should be the full URL to which to map. For client autoconfiguration mappings, this value should be the absolute path to the .pac file on the proxy server’s hard disk. For proxy array table mappings, this value should be the absolute path to the .pat file on the master proxy’s local disk.

  6. Select the template name from the drop-down list, or leave the value at NONE if you do not want to apply a template.

  7. Click OK to create the mapping.

  8. Click Restart Required.

    The Apply Changes page is displayed.

  9. Click the Restart Proxy Server button to apply the changes.

ProcedureTo Change Your Existing Mappings

  1. Access the Server Manager and click the URLs tab.

  2. Click the View/Edit Mappings link.

    The View/Edit Mappings page is displayed.

  3. Click the Edit link next to the mapping to be modified. You can edit the prefix, the mapped URL, and template that are affected by the mapping. Click OK to confirm your changes.

  4. Click Restart Required. The Apply Changes page is displayed.

  5. Click the Restart Proxy Server button to apply the changes.

ProcedureTo Remove a Mapping

  1. Access the Server Manager and click the URLs tab.

  2. Click the View/Edit Mappings link.

    The View/Edit Mappings page is displayed.

  3. Select the mapping to be removed, then click the Remove link next to it.

  4. Click Restart Required. The Apply Changes page is displayed.

  5. Click the Restart Proxy Server button to apply the changes.

Redirecting URLs

You can configure the proxy server to return a redirected URL to the client instead of getting and returning the document. With redirection, the client is aware that the URL originally requested has been redirected to a different URL. The client usually requests the redirected URL immediately. Netscape Navigator automatically requests the redirected URL. The user does not have to explicitly request the document a second time.

URL redirection is useful when you want to deny access to an area because you can redirect the user to a URL that explains why access was denied.

ProcedureTo Redirect One or More URLs

  1. Access the Server Manager and click the URLs tab.

  2. Click the Redirect URLs link. The Redirect URLs page is displayed.

  3. Type a source URL that is a URL prefix.

  4. Type a URL to redirect to. This URL can either be a URL prefix or a fixed URL.

    • If you choose to use a URL prefix as the URL to redirect to, select the radio button next to the URL prefix field and type a URL prefix.

    • If you choose to use a fixed URL, select the radio button next to the Fixed URL field and type a fixed URL.

  5. Click OK.

  6. Click Restart Required.

    The Apply Changes page is displayed.

  7. Click the Restart Proxy Server button to apply the changes.