7.2 Useful Files for Troubleshooting the Access Gateway Appliance

7.2.1 Viewing Log Files

Table 7-3 describes the Linux Access Gateway files that contain troubleshooting information.

Table 7-3 Log Files with Troubleshooting Information

Log File

Description

catalina.out

Located in the /var/opt/novell/tomcat5/logs directory and available from the General Logging page in the Administration Console.

The Embedded Service Provider, which communicates with the Identity Server, writes to this log file. The log level is controlled by the Identity Server Configuration. For configuration information, see Turning on Logging for Policy Evaluation in the Novell Access Manager 3.1 SP1 Policy Management Guide.

For information on how to use the entries for policy troubleshooting, see Troubleshooting Access Manager Policies in the Novell Access Manager 3.1 SP1 Policy Management Guide.

ics_dyn.log

Located in the /var/log directory and available from the General Logging page in the Administration Console.

The proxy service writes to this log file. For information on enabling logging to this file, see Gateway Appliance Logs.

For maximum verbosity, the proxy service must be started in debug mode. See Table 7-2, novell-vcm Commands.

lagsoapmessages

Located in the /var/log directory and available from the General Logging page in the Administration Console.

When enabled, this file contains a log of the SOAP messages between the Linux Access Gateway and the Embedded Service Provider for authentication (roles, contracts, and timeouts) and policy interaction (Authorization, Form Fill, and Identity Injection).

For information on enabling logging to this file, see Configuring Logging of SOAP Messages and HTTP Headers.

laghttpheaders

Located in the /var/log directory and available from the General Logging page in the Administration Console.

When enabled, this file contains a log of the HTTP headers to and from the Linux Access Gateway.

For information on enabling logging to this file, see Configuring Logging of SOAP Messages and HTTP Headers.

7.2.2 Using Touch Files

Table 7-4 describes the touch files that control configuration options for Linux Access Gateway that aren’t available from the Administration Console. Filenames are case-sensitive.

Table 7-4 Touch Files

Filename

Description

.~newInstall

Located in the /var/novell directory.

The Linux Access Gateway creates this file by default during every start.

If you want the Linux Access Gateway to come up without the contents cached in the previous run, or to purge all cache, remove this file before you restart the Linux Access Gateway.

.modVia

Located in the /var/novell directory.

Adds the device ID in the Via header that is sent by the Linux Access Gateway to the Web server.

The Linux Access Gateway sends the Via header in the following format:

Via: 1.0 www.mylag.com (Access Gateway 3.0.1-72-D06FBFA8CF21AF45)

.enableInPlaceSilentFill

Located in the /var/novell directory.

To be used for the Linux Access Gateway Form Fill. When this touch file is used, the login page is not modified.This enables single sign-on to certain Web sites that require the login page to remain as is without any modifications to its structure.

When this touch file is used, the Linux Access Gateway does not generate a new page if autosubmit is enabled, but fills the page received from the Web server and hides the text/password/unspecified type fields. Form-Fill issues for CRM applications and teaming and conferencing applications are resolved with this touch file.

However, when this touch file is used, the Debug Submit and JS Functions to Keep options of the Form Fill policy do not work.

.enableInPlaceSilentFillNew

Located in the /var/novell/ directory.

This touch file is to be used to fill forms with complex JavaScript or VBScripts. You must use this touch file along with the .enableInPlaceSilentFill file. To use this file, the Form Fill policy must have the Statements To Execute on Submit option enabled and the policy must contain a function to execute as shown in the following example: 

    function anynamefunction() { 
             ...some statements... 
    } 
    function executeJavaScript() { 
              <<... any functions you want to be called..>> 
              document.forms[0].submit(); 
    }

lagDisableAuthIPCheck

Located in the /etc directory.

Enabling this touch file switches off the proxy authentication cookie binding to client IP. Use this in a setup where two L4 switches are configured in parallel and the browser requests get bounced between the these L4 switches.

.alwaysUseJSFor302

Located in the /var/novell directory.

Uses JavaScript for redirection. A 200 OK response is sent back with the redirect metatag instead of the 302 redirect, when this touch file is used.

.useJSFor302withIE7

Located in the /var/novell directory.

When Internet Explorer 7 browser is used, 200 OK response is sent back with the redirect metatag instead of the 302 redirect.

.useRelativeUrlInJS

Located in the /var/novell directory.

Sends back the 200 OK response with the metatag redirect header referencing a relative URL rather than full URL (scheme, host, path). This touch file should be used when .useJSFor302withIE7 and alwaysUseJSFor302 files are used.

.useHTMLBodyIn302

Located in the /var/novell directory.

The Linux Access Gateway sends 302 redirects without any content by default.

When this file is present, the following content is sent for any 302 redirects:

<html><head><title>Redirection</title></head><body>Your browser should support redirection.</body></html>

.forceUTF8CharSet

Located in the /var/novell directory.

When this file is enabled, the Linux Access Gateway serves the Form Fill page to the browser in the UTF-8 character set.

.ignoreDnsServerHealth

Located in the /var/novell directory.

Ignores the DNS server health status while reporting health to the Administration Console.

.EnableSecureCookie

Located in the /var/novell/ directory.

Adds the word secure at the end of set-cookie so that only HTTPS sites can access it. This file works when the Force Secure Cookie option is disabled in the Administration Console.

.noURLNormalize

Located in the /var/novell/ directory.

Disables the URL normalization protection for back-end Web servers. This touch file resolves issues in serving Web content from Web servers which had double byte characters such as Japanese language characters.

.AllowUnknownHTTPMethods

Located in the /var/novell/ directory.

When this file is present, the Linux Access Gateway forwards any unknown HTTP methods to the Web server.

.noGzipSupport

Located in the /var/novell directory.

Disables GZIP functionality in the Linux Access Gateway.

This ensures that the Linux Access Gateway does not send Accept-Encoding: gzip deflate headers to the Web server.

.useAlternate

Located in the /opt/novell/conf/keys directory.

This file can be used when you have problems with the SSL listeners in the Linux Access Gateway. The following error message is displayed in the ics_dyn.log:

NiciStore unprotect data failed

When you use this file, re-push the certificates used by the Linux Access Gateway listeners, apply the changes, then restart the Linux Access Gateway.

.doNotUseTLS

Located in the /var/novell directory.

Use this touch file if there is a problem in accelerating Oracle application servers. After creating the touch file, restart the Linux Access Gateway. When this file is enabled, it prevents the Linux Access Gateway from using TLS to communicate with the back-end Web servers.

.ForceHTTPSSchemeInESPRedirection

Located in the /var/novell directory.

Forces the Linux Access Gateway to always return the URL in the HTTPS schema.

Use this if the Linux Access Gateway is located behind an SSL terminator. In this case, the original URL accessed by the browser is rewritten with the HTTPS scheme. This ensures that the traffic is sent back to the browser after the authentication contains the right protocol (SSL/TLS).

.overwrite_AuthHeader_With_IIData

Located in the /var/novell directory.

This touch file ensures that when a browser sends an authentication header, the Linux Access Gateway Appliance overwrites it with the authentication header configured in the Identity Injection policy.

.PasswordMgmt

Located in the /var/novell directory.

Use this touch file to refresh the user’s credentials to match password changes.

You must use this touch file if you have configured resources to use Identity Injection policies to inject the user’s password and the Identity Server is configured to use a password management service.

If this touch file is not enabled, when users authenticate and change their credentials, the Access Gateway uses the old password for identity injection.

.enableichaincompatibility

Located in the /var/novell directory.

Does protected resource matching, similar to iChain.

.matchLagIchainCookieName

Located in the /var/novell directory.

Forwards a proxy session cookie to a back-end application.

Cookie without a touch file looks like:

IPCZQX03a36c6c0a=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Cookie with a touch file looks like:

IPCZQX01a36c6c0a=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

.spnetworkplaces

Located in the /var/novell directory.

Helps user to use Microsoft Network Places client to connect to WebDAV folders such as SharePoint that is accelerated by Linux Access Gateway as path-based multi-homing service.

For this touch file to function as specified, you should add the following lines to the file, and restart Linux Access Gateway.

  • SHAREPOINTPATH=/<accelerated path>
  • HOSTNAME=<accelerated host name>

.AllowMSWebMiniRedir

Located in the /var/novell directory.

Helps the user to disable the following functionality which is enabled by default:

If a client (Windows network place) sends an OPTIONS request with MS-WebDAV-MiniRedir user-agent to Linux Access Gateway, then it receives 409 conflict response. The client uses this response to change the user-agent to MS Data Access Internet Publishing Provider DAV.

.reqPostSize

Located in the /var/novell directory.

Helps user to specify POST size up to 50 MB. POST size defaults to 1 MB without this touch file.

In this touch file, configure the POST size as:

REQPOSTSIZE=<value in terms of MB>

Even if you specify a value greater than 50 MB, the value limits to 50 MB.

.rewriteAlwaysHTTPS

Located in the /tmp directory.

If this touch file is enabled, Linux Access Gateway rewrites all HTTP links to HTTPS while serving to the browser.

.modifyRequestURI

Located in the /var/novell directory.

When clients use Internet Explorer and MS office 2007 to access SharePoint resources protected by Access Gateway, some requested URLs are not sent to the correct path-based proxy service.

For example, assume that the SharePoint server is accelerated by a reverse proxy service https://sharepoint.CompanyA.com/share1. The browser, instead of sending the request URL as https://sharepoint.CompanyA.com/share1/_vti_bin/webs.asmx., sends the URL as https://sharepoint.CompanyA.com/_vti_bin/webs.asmx, without the path /share1.This causes Access Gateway to serve request to the wrong service.

To workaround this problem, configure the .modifyRequestURI file with the following information:

  • Published DNS name of the proxy service accelerating the SharePoint server.

  • URLs that require path injection in the request URL.

  • Path (or paths) of the SharePoint service under this proxy service, that must be prepended to the listed URLs.

An example file looks similar to the following:

HOSTNAME=sharepoint.CompanyA.com
PATH1=/share1 
PATH2=/share2
URL1=/_vti_bin/webs.asmx
URL2=/_vti_bin/lists.asmx
URL3=/_vti_bin/Copy.asmx
URL4=/_vti_inf.html

NOTE: If you are adding multiple paths, make sure that these path-based services belong to the same domain.

When this file is present with the required configuration, the incoming request URL is compared with the URLs in the touch file. If a match is found and the host name of request URL matches the HOSTNAME value, then the following occurs:

  • If only one path is configured, the path is injected to the request, and the request is sent to this path-based service.

  • If multiple paths are configured, Access Gateway looks for the last path-based service accessed by this user. This path is injected to the request, and the request is sent to this path-based service.

 

For example, if the last resource accessed by User A is https://sharepoint.CompanyA.com/share2/ and the next URL request is https://sharepoint.CompanyA.com/_vti_bin/webs.asmx, the request URL is changed to https://sharepoint.CompanyA.com/share2/_vti_bin/webs.asmx and the request is sent to /share2.

.setsecureESP

Located in the /var/novell directory.

When this touch file is used, the JSESSIONID cookie of the Embedded Service provider is marked as secure.

To enable this touch file, you need one of the following:

  • All services that need authentication must use the secure communication channel or HTTPS.

  • Access Gateway device must be behind an SSL terminator.

For more information, see Section 2.5.1, Securing the Embedded Service Provider Session Cookie

.releaseclosewait

Located in the /var/novell directory.

This touch file is useful if Linux Access Gateway goes into a non-responsive mode and there are a large number of connections in the close_wait state in the public listener port. You can use this touch file to enable the forced cleanup of connections in a close_wait state.

The Linux Access Gateway must be restarted in order to get the desired functionality. Use the following command to restart when a touch file is created or removed:

/etc/init.d/novell-vmc stop

/etc/init.d/novell-vmc start

Creating a File

To create a file, use the following command as a root user:

touch <pathname>/<filename>

For Example, touch /var/novell/.modVia

Removing a File

To remove a file, use the following command as a root user:

rm <pathname>/<filename>

For example, rm /var/novell/.modVia