7.2 Using Log Files and Touch Files to Troubleshoot the Access Gateway Appliance

7.2.1 Viewing Log Files

Table 7-3 describes the 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 SP5 Policy Guide.

For information on how to use the entries for policy troubleshooting, see Troubleshooting Access Manager Policies in the Novell Access Manager 3.1 SP5 Policy 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 Access 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 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 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

This section describes the touch files that control configuration options for the Access Gateway Appliance that aren’t available from the Administration Console. Filenames are case-sensitive.

The Access Gateway Appliance 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

NOTE:If you have the Linux Access Gateway Appliance in cluster, create or remove the corresponding touch file in all the cluster members.

This section has the following information:

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

List of Touch Files

.dumpcore

To enable a core dump, create the following touch file:

/tmp/.dumpcore

The lagmonitor service creates and checks for the /var/novell/.lowdiskspacex file, when it detects low disk space.

NOTE:If the lagmonitor service is running and there is low free disk space in the root partition, then ics_dyn might not dump core with the above setting.

If you want to force a core dump without worrying about the disk space availability, use the following file:

touch /tmp/.forcedumpcore touch file.

.~newInstall

This file is located in the /var/novell directory. The Access Gateway creates this file by default during every start.

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

.disabletoppr

This file is located in the /var/novell directory. If the Access Gateway machine running near capacity, user sessions might be logged out and the users might see the login page intermittently. If you are experiencing disconnect problems or performance problems, you can enable this touch file to determine whether the problem is related to the timeout per protected resource feature.

To disable the timeout per protected resource feature, enable the /var/novell/.disabletoppr touch file.

.modVia

This file is located in the /var/novell directory. This adds the device ID in the Via header that is sent by the Access Gateway to the Web server.

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

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

This file is Located in the /var/novell directory.

To be used for the 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 Access Gateway does not generate a new page if auto submit 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 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. For more information on how to use this touch file, seeConfiguring a Form Fill Policy for Forms With Scripts in the Novell Access Manager 3.1 SP5 Policy Guide.

.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. For more information on how to use this touch file, seeConfiguring a Form Fill Policy for Forms With Scripts in the Novell Access Manager 3.1 SP5 Policy Guide.

.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.

  • The Access Gateway device must be behind an SSL terminator.

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

.lagDisableAuthIPCheck

This file is located in the /etc directory.

If this touch file is enabled, the Access Gateway does not perform the IP address check on incoming session cookies. Use this in a setup where two L4 switches are configured in parallel and the browser requests are bounced between these L4 switches.

For example, if multiple back-end Web servers are accelerated by the Access Gateway, some users complain that they are not able to complete their logins. When they access the protected resources, they are redirected to the Identity Server for authentication, but they are not redirected to the original URL.

If multiple paths (at the network level) exist between a browser and the Access Gateway and proxies or NAT devices exist on these paths, it is possible that the source IP address of the incoming requests into the Access Gateway might change. For example, assume that user A connects to an ISP. This ISP has multiple transparent proxies in parallel for performance reasons.

User A accesses the Access Gateway for the first time. The request from User A goes through a local transparent proxy TP1, so the incoming IP address of the initial request has that transparent proxy's (TP1) IP address. The Access Gateway session cookie is set and the user is redirected back to the page he/she was going to originally

User A then sends the next request for this original page, but it goes through a different proxy, TP2. The incoming IP address of the request into the Access Gateway is now different than the one that the user used for authentication (TP1 IP address) and the validation fails. The Access Gateway loops as it continues to request the user to send a valid session cookie.

.alwaysUseJSFor302

This file is located in the /var/novell directory.

This file uses JavaScript for redirection. When this touch file is used, a 200 OK response is sent back with the redirect metatag instead of the 302 redirect.

.useJSFor302withIE7

This file is located in the /var/novell directory.

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

.useRelativeUrlInJS

This file is located in the /var/novell directory.

This file 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 the .useJSFor302withIE7 and alwaysUseJSFor302 files are used.

.useHTMLBodyIn302

This file is located in the /var/novell directory.

By default, the Access Gateway sends 302 redirects without any content.

When this touch 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

This file is located in the /var/novell directory.

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

.ignoreDnsServerHealth

This file is located in the /var/novell directory.

When this touch file is used, the DNS server health status is ignored when the Access Gateway health is reported to the Administration Console.

.noURLNormalize

This file is located in the /var/novell/ directory.

This file disables the URL normalization protection for back-end Web servers. It resolves issues in serving Web content from Web servers that have double-byte characters such as Japanese language characters.

.AllowUnknownHTTPMethods

This file is located in the /var/novell/ directory.

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

.noGzipSupport

This file is located in the /var/novell directory.

This file disables GZIP functionality in the Access Gateway.

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

.useAlternate

This file is located in the /opt/novell/conf/keys directory.

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

NiciStore unprotect data failed

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

.doNotUseTLS

This file is 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 Access Gateway. When this file is enabled, it prevents the Access Gateway from using TLS to communicate with the back-end Web servers.

.overwrite_AuthHeader_With_IIData

This file is located in the /var/novell directory.

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

.PasswordMgmt

This file is located in the /var/novell directory.

Use this 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.

.matchLagIchainCookieName

This file is located in the /var/novell directory.

This file forwards a proxy session cookie to a back-end application.

A cookie without this touch file enabled looks like:

IPCZQX03a36c6c0a=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A cookie with this touch file enabled looks like:

IPCZQX01a36c6c0a=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

.spnetworkplaces

This file is located in the /var/novell directory.

This file enables users who use the Microsoft Network Places client to connect to the WebDAV folders of a SharePoint server when the SharePoint server has been configured as a path-based multi-homing service on the Access Gateway.

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

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

This file is located in the /var/novell directory.

This file helps the user to disable the following functionality, which is enabled by default:

If a Microsoft Network Places client sends an OPTIONS request with MS-WebDAV-MiniRedir user-agent to the 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

This file is located in the /var/novell directory.

This file enables users to specify POST size up to 50 MB. POST size defaults to 1 MB without this touch file.

In the touch file, add the following line to configure the POST:

REQPOSTSIZE=<value in terms of MB>

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

.disableClientRenego

The touch file is located in the /var/novell directory.

When you configure this file, it disables the browser initiated renegotiation.

.disableExternalDNSRewrite

This file is located in the /var/novell directory.

When this touch file is present and the Remove path on fill option is enabled, the Access Gateway does not insert the path for the links with external published DNS.

.modifyRequestURI

This file is located in the /var/novell directory.

When clients use Internet Explorer and MS office 2007 to access SharePoint resources protected by the 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 the Access Gateway to serve the request to the wrong service.

To work around 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. The paths 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 the request URL matches the HOSTNAME value, 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.

.ParkingSizeInKiloBytes

This file is located in the /etc/opt/novell directory.

This file enables users to increase the limit of the post parking size. Edit the file /etc/opt/novell/postParkingSizeInKiloBytes.cfg

To increase the limit of post parking size, perform the following:

  • echo “400” > /etc/opt/novell/postParkingSizeInKiloBytes.cfg

  • A configuration change from the Administration Console or /etc/init.d/novell-vmc restart.

    NOTE:There is maximum limit of 2048 kilobytes, to increase the limit create a touch file /etc/opt/novell/.ignorePostParkingSizeLimit along with the above mentioned steps. Configuring higher size for post parking can potentially increase the memory footprint of the ics-dyn process and might result in a process restart (if the memory consumption is high). The default value is 50 kilobytes.

.doURLEncodewithSB

This file is located in the /var/novell directory.

To work around the encoded or double byte character username issue, create the touch file /var/novell/.doURLEncodewithSB as the other Linux Access Gateway members in the cluster might not understand the encoded username.

After creating the touch file, restart the novell-vmc process.

NOTE:Enable the touch file only after upgrading all the Linux Access Gateway members of the cluster to 3.1.3 IR2 or higher.

.disableWSHealth

This file is located in the /var/novell directory. Create the touch file /var/novell/.disableWSHealth , the Linux Access Gateway does not mark status “failed” based on the Web Server reachability.

.allowSSLV2

This file is located in the /var/novell directory. Create the touch file /var/novell/.allowSSLV2. This file enables the Linux Access Gateway Appliance to communicate to the Web server over SSL V2.

.allowCRLF

This file is located in the /var/novell directory. Create the touch file /var/novell/.allowCRLF. This file enables the Linux Access Gateway Appliance to serve the request which has (Carriage Return 0x0D) and (Linefeed 0x0A) characters in the URI.

.ffPrompt4NoneOrNA

This file is located in the /var/novell directory. Create the touch file .ffPrompt4NoneOrNA. This file enables Linux Access Gateway to prompt you to fill the shared secret values that have either not available or empty.

.newFFMask

This file is located in the /var/novell directory. Create the touch file .newFFMask. With this touch file, the Access Gateway will mask the data as nov-ss-ff-masked+mangledValue instead of nov-ss-ff-masked. The appended mangledValue helps any Linux Access Gateway in the cluster to unmask the data.