Configure the Virtual Host Settings Manually

Contents
casso1283
Contents
The virtual host settings let
Access Gateway
act as a virtual host. You must define one default virtual host and can define multiple virtual hosts. By default,
Access Gateway
provides default virtual host settings that can be used for all the virtual hosts in the server.conf file that is located as follows:
  • Windows
    :
    <ag_home>
    \secure-proxy\proxy-engine\conf\web.xml
  • UNIX
    :
    <ag_home>
    /secure-proxy/proxy-engine/conf/web.xml
If you want to override the default virtual host settings for a virtual host, create a virtual host with the new values. If you do not define virtual host settings during the virtual host creation,
Access Gateway
uses the default value that is defined in the default virtual host settings.
Default Virtual Host Values
The default virtual host settings consist of the following sections:
  • Virtual host details
  • Default session scheme
  • Session scheme mappings
  • Web Agent configuration
Setting Virtual Host Cookie Path and Domain to the Correct URI
The virtual host configuration in the server.conf file includes the
enablerewritecookiepath
and
enablerewritecookiedomain
parameters for managing cookies generated by a destination server that sits behind
Access Gateway
. When
Access Gateway
receives a request from a client,
Access Gateway
authenticates the user and directs the client to the requested destination server. The destination server generates a cookie that it places in the browser, then
Access Gateway
sends the user back the client response with the cookie. After receiving the response from
Access Gateway
, the client stores the cookie.
When the client sends a subsequent request, the browser retrieves the stored cookie associated with the URL. In some cases, the destination server can possibly have set the cookie path to its own resource URI and not to the URI of the initial request. As a result, when the client sends the subsequent request, the browser contains the wrong cookie or does not even have a cookie. The request is received at the destination server with the wrong cookie or with no cookie at all.
To ensure that the correct cookie is set in the browser, you can configure
Access Gateway
to rewrite the cookie path and cookie domain. The destination server sets the cookie path and cookie domain to the URI of the resource on
Access Gateway
server. The client can send the correct cookie back with subsequent requests to
Access Gateway
.
The two parameters operate as follows:
  • enablerewritecookiepath
    Instructs
    Access Gateway
    to rewrite the cookie path to the URI of the initial request from the URI set by the server that sits behind the proxy.
    Default
    : no
  • enablerewritecookiedomain
    Instructs
    Access Gateway
    to rewrite the cookie domain from the domain set by the server sitting behind the proxy to the domain of the initial request.
    Default
    : no
For example, consider that a client requests a resource named http://myag.ca.com/basic/test/page0.html. With the
enablerewritecookiepath
set to
yes
, the cookie path is rewritten to
/basic/test
before the browser is sent back to the client. This cookie is rewritten regardless of the cookie path that was originally in the cookie received by Instructs
Access Gateway
from the destination server.
To rewrite backend cookie paths and domain, perform the following steps:
  1. Open the server.conf file in a text editor.
  2. Set one or both of the following parameters to
    yes
    :
    • enablerewritecookiepath
    • enablerewritecookiedomain
  3. Save the file.
  4. Restart
    Access Gateway
    .
Preserve the HOST Header File
You can preserve the HTTP HOST header file and send it to the backend server by using the
enableproxypreservehost
parameter. To use the parameter, perform the following steps:
  1. Open the server.conf file.
  2. Add the
    enableproxypreservehost
    parameter in the Virtual Host section of the virtual host that you want to configure.
  3. Set the value of
    enableproxypreservehost
    to
    yes
    .
When you enable
enableproxypreservehost
, the parameter takes precedence over a filter that is configured to control the HTTP HOST header. To disable
enableproxypreservehost
and let the filter take precedence over the parameter, perform the following steps:
  1. Open the server.conf file.
  2. Add the
    filteroverridepreservehost
    parameter in the Virtual Host section of the virtual host that you want to configure.
  3. Set the value of
    filteroverridepreservehost
    to
    yes
    .
You can enable filteroverridepreservehost only if a filter is available to control the HTTP HOST header.
Handling Large Files Using Data Blocks
Access Gateway
handles the transfer of large files to users by breaking up the data that is transferred between
Access Gateway
and the backend server into blocks. You control the block size read by
Access Gateway
using two parameters in the Virtual Host section of the server.conf file:
  • requestblocksize
  • responseblocksize
When a user sends a file to a backend server,
Access Gateway
verifies the requestblocksize specified for that virtual host. Based on the value of requestblocksize,
Access Gateway
breaks down the data into blocks and then forwards the blocks to the backend server.
Similarly, when the backend server sends data to the user,
Access Gateway
verifies the responseblocksize specified for that virtual host. Based on the value of responseblocksize,
Access Gateway
reads the data in blocks from the backend server before further processing the blocks. This enables the user to control the number of read-write operations for such file transfers. To handle large file transfers, use large block sizes.
Note
: The requestblocksize and responseblocksize parameters should be defined in a proportion to the available and allocated JVM heap size for
Access Gateway
java process.
Define File Data Block Size for Large File Handling
To define the block size to handle large files when you configure the block size for a virtual host, modify the request and response block sizes for each virtual host. These parameters are valid only for that virtual host. The data block sizes can be different for different virtual hosts, but the settings only apply to the associated virtual host you are configuring.
Follow these steps
:
  1. Open the server.conf file in a text editor.
  2. Edit the following parameters under the virtual host configuration:
    • requestblocksize
      Defines the block size of the request data that is read at a time before the data blocks are sent to the backend server. The block sizes are in KB.
      Limits
      : 1KB to approximately 352000 KB. For any value greater than or equal to 8 KB, chunks of 8 KB are created. A corresponding chunk size is create for values between 1 KB and 8 KB.
      Default
      : 4
    • responseblocksize
      Defines the block size of the response data that will be read at a time before the data blocks are forwarded from the backend server to the user. The block sizes are in KB.
      Limits
      : 1KB to approximately 352000 KB.
      Default
      : 8
  3. Save the server.conf file.
  4. Restart
    Access Gateway
    .
Adjust JVM Heap Size for Data Blocks
The
requestblocksize
and
responseblocksize
parameters are defined in proportion to the available and allocated JVM heap size for
Access Gateway
java process.
Follow these steps
:
  1. Navigate to the appropriate directory:
    • Windows
      :
      <ag_home>
      /secure-proxy/proxy-engine/conf
    • UNIX
      :
      <ag_home>
      /secure-proxy/proxy-engine
  2. Open one of the following files:
    • Windows
      : SmSpsProxyEngine.properties file
    • UNIX
      : proxyserver.sh file
  3. Add the following parameters in the Java section of the file:
    • –Xms256m
    • –Xmx512m
  4. Save the file.
Session Scheme Mapping for the Default Virtual Host
Session scheme mappings associate session schemes with user agent types. The user agent types defined in elements of the server.conf file must be mapped to session schemes defined in the elements.
The directive in session scheme mapping is:
  • user_agent_name
    Associates a user agent with a session scheme. To set the values:
    • user_agent_name
      Specifies a name defined in a section of the file
    • session_scheme_name
      Specifies a scheme defined in a SessionScheme element.
Example
: User Agents named browser, phone1, and phone2 have been defined and mapped to any of the session schemes defined in the file. For this example, browser is mapped to the default session scheme, phone1 is mapped to the simple_url scheme, and phone2 is mapped to the minicookie session scheme. The resulting element appears as follows:
# Session Scheme Maps <SessionSchemeMappings> browser="default" phone1="simple_url" phone2="minicookie" </SessionSchemeMappings>
Web Agent Settings for the Default Virtual Host
The server.conf file includes a section for the <VirtuallHostDefaults>. The sminitfile directive specifies the configuration file, WebAgent.conf for the default web agent. If local configuration is allowed, the WebAgent.conf file points to a local configuration file, LocalConfig.config.
If you create more than one virtual host, you can use the default Web Agent when you do not intend to use alternate settings in the Web Agent configuration file. If you plan to set any directive differently, for example, to specify a different log level, use a different Web Agent for the new virtual host.
To configure a new Web Agent for a new virtual host, perform the following steps:
  1. Create a directory with the name of the new virtual host, for example, serverb.
  2. Copy the contents of the directory for the default virtual host into the new directory.
  3. Run smreghost if the new Web Agent points to a different SiteMinder installation.
    Note
    : If the Web Agent configuration objects for both virtual hosts point to the same SiteMinder installation, you do not need to run smreghost. You can use the same smhost file for both the Web Agents.
  4. Use a text editor to modify WebAgent.conf to reflect the new agent configuration object. Verify that the Web Agents have different log files.
  5. Open the WebAgent.conf file and add the following required directive with a unique value.
    ServerPath="
    path
    "
    path
    Specifies is the fully qualified path to the WebAgent.conf file that you are editing. On Windows, this value must be a unique alphanumeric string. The backslash '\' character is not permitted in this string. On UNIX, this value must be the fully qualified path to the WebAgent.conf file that you are editing.
  6. Access the Agent Configuration Object at the Policy Server that corresponds to the first host configuration object in the server.conf file. Verify the Agent cache settings for MaxResoureceCacheSize and MaxSessionCacheSize and also that the cache limits take into account all Agent Configuration Objects.
Setting the requirecookies Parameter
The
requirecookies
setting in the server.conf file is a special Web Agent setting that is useful only if basic authentication was set during the Policy Server configuration. This setting instructs the agent to require either an SMSESSION or an SMCHALLENGE cookie to process HTTP requests successfully, including basic Authorization headers.
If you configure the embedded Web Agent to require cookies, the browser must accept HTTP cookies. If the browser does not, the user receives an error message from the Agent denying them access to all protected resources.
Set the
requirecookies
setting to
yes
when all user agent types for the associated virtual server use the default session scheme. If an agent type uses a cookieless session scheme, set the
requirecookies
parameter to
no
.
Handling Redirects by Destination Servers
Some destination servers can respond to a request from the
Access Gateway
with a redirection.
A redirection that is the result of a request to the
Access Gateway
is not the same as a redirect that occurs in a proxy rule. For information about a redirect in a proxy rule, see nete:redirect.
Because the redirection initiated by the destination server is likely to a server behind the DMZ, the URL specified in the redirection results in an error. However, you can include parameters in a virtual host configuration that substitute the virtual host server name and port number in place of a redirect from a destination server.
To substitute the virtual host server and port for redirect writing, configure the following:
  • enableredirectrewrite
    Enables or disables redirect rewriting. If this directive is set to a value of yes, the URL for a redirect initiated by a destination server is examined by the
    Access Gateway
    . If the redirect URL contains a string found in the list of strings specified in the associated redirectrewritablehostnames parameter, the server name and port number of the redirect are replaced by the server name and port number of the virtual host. If the parameter is set to a value of no, any redirects initiated by destination servers are passed back to the requesting user.
  • redirectrewritablehostnames
    Contains a comma-separated list of strings that the
    Access Gateway
    searches for when a redirection is initiated by a destination server. If any of the specified strings are found in the server or port portion of the redirect URL, the
    Access Gateway
    substitutes the name and port number of the virtual host for the server name and port portion of the redirect URL. If you specify a value of "ALL" for this parameter, the
    Access Gateway
    substitutes the server name and port number of the virtual host for all redirects initiated by the destination server.
For example, consider a virtual host configuration in the server.conf file that contains the following parameters:
<VirtualHost name="sales"> hostnames="sales, sales.company.com" enableredirectrewrite="yes" redirectrewritablehostnames="server1.company.com,domain1.com" </VirtualHost>
When a user makes a request from http://sales.company.com:80, the
Access Gateway
forwards the request to a destination server according to proxy rules. If the destination server responds with a redirect to server1.internal.company.com, the redirect is rewritten before being passed to the user as sales.company.com:80.
The proxy rules for the
Access Gateway
must be configured to handle the redirected requests.
Default Virtual Host
To let
Access Gateway
act as a virtual host for one or more host names, you must define a virtual host as the default virtual host. You can define multiple virtual hosts.
To manually configure a default virtual host, modify the <VirtualHost name="default"> section in the server.conf file.
Create Virtual Host
You can define multiple virtual hosts and configure them to different settings other than the default virtual host values.
Follow these steps:
  1. Open the server.conf file.
  2. Create a virtual host section in the server.conf file with the fields as described in the default virtual host values.
    If you do not define any settings, its default value is considered from the default virtual host values.
  3. Save the changes.
Override Default Values for Virtual Hosts
The <VirtualHostDefaults> settings are used for all virtual hosts defined in the server.conf file unless you explicitly enter settings for a particular virtual host. You do not have to reconfigure all the virtual settings for the single virtual host. Any settings that you do not redefined in the VirtualHost> element are applied from the <VirtualHostDefaults> settings.
Follow these steps
:
  1. Add any directive in the default virtual host configuration to the <VirtualHost> element that you want to modify.
  2. Specify a new value for the directive in the <VirtualHost> element.
  3. Save the file.
  4. Restart
    Access Gateway
    .
Example
: The virtual host named "sales" requires a default session scheme from what is configured for the default virtual host. The <VirtualHost> element could be modified as follows:
<VirtualHost name="sales"> hostnames="sales, sales.company.com" addresses="123.123.22.22" defaultsessionscheme="minicookie" </VirtualHost>