17.2 The Custom Rewriter

The Novell iChain custom rewriter (rewrite.nlm) was developed because of the need to replace URL text pieces. For example, a document could have the following JavaScript variables:

var scheme = “http://”
var host = “internal.web.site.com”
var path = “/path/”
var file = “file1.html”
var URL = scheme + host + path + file;

These variables are used to build URL strings for the user. The internal rewriter can only rewrite true URL references such as http://internal.web.site.com/path/file1.html to the schema and hostname of the accelerator that accesses the internal Web site (https://mynovell.com/path/file1.html).

The custom rewriter also enables administrators to search and replace user-specified strings with new strings. For example, a user might want to change all occurrences of “President” to “Secretary” in the data portion of the page.

The custom rewriter has an overlapping region problem when used in conjunction with the internal rewriter. If both rewriters want to change the same characters of data within a file, it is undefined which rewriter takes precedence. In some cases, a few of characters around the rewritten area are lost or added. This problem happens when the custom rewriter is used to rewrite the same URLs that the internal rewriter also rewrites. The custom rewriter was not developed to search and replace full URL references; only URL pieces (as shown in the above example)

The following sections explain how the custom rewriter works and how to configure it:

17.2.1 Rewrite Filter Configuration File

You configure the custom rewriter by creating a rewrite filter in a text file. The custom rewriter reads the configuration file and replaces all occurrences of a user-specified string with the specified replacement string, irrespective of the location of the original string in the data. An example of a configuration file is given below:

[Name=oraclefilter]

[Extension]
html, htm

[Mime Content-Type]
Text/html, text/css

[URL]
sjf-siva.sjf.novell.com/oracle/*
sjf-siva.sjf.novell.com/database/OracleQuery.html
sjf-siva.sjf.novell.com/oraclereports/

[Replace]
var xsport     =”9003”<<>> var xsport    =”443”
var xsname     =”xyz01”<<>> var xsname   =”www”
var xconnectMode = “http”<<>> var xconnectMode = “https”
<PARAM name=serverHost   value=”xyz01.novell.com”><<>><PARAM name=serverHost  value=”www.novell.com”>
<PARAM name=serverPort value=”9003”><<>><PARAM name=serverPort value=”443”>
<PARAM name=connectMode value=”https”><<>><PARAM name=connectMode  value=”http”

This file has the following elements:

[Name=<filtername>]: The name of the rewriter filter. It is used for filter identification in rwfilter commands.

[Extension]: The user can specify file extensions (in a single line) that need to be parsed. This section is optional, but if this section is not specified, all extension types are parsed. Specifying this section results in parsing only specified extensions.

NOTE:If possible, you should use an [extension] section. Otherwise, the custom rewriter processes all kinds of files (including .zip files and .iso files).

All extensions should be specified in a single line (just after the Extensions section header). Individual extension elements should be separated by a comma.

For example:

[Extension]
html

This entry enables the following behavior:

  • Parses files with html extensions.

  • Parses http://www.novell.com/index.html.

  • Does not parse http://www.novell.com/logo.gif.

  • Does not parse http://www.novell.com.

For example:

[Extension]
html, htm, txt

This entry enables the following behavior:

  • Parses files with extensions html, htm, txt, and any default files implied by a trailing slash (/).

  • Parses http://www.novell.com/license.txt.

  • Parses http://www.novell.com/.

  • Does not parse http://www.novell.com/logo.gif.

[Mime Content-Type]: The user can specify mime types to be rewritten by the custom rewriter. If this section is present, it takes precedence over the [Extension] section. Any files that match the mime type are rewritten, regardless of their extension.

All mime types should be specified in a single line (just after the mime content-type section header). Individual mime-type elements should be separated by a comma.

For example:

[Mime Content-Type]
text/html

This entry enables the following behavior:

  • Parses files with extensions as a mime type text/html.

  • Parses http://www.novell.com/index.html.

  • Does not parse http://www.novell.com/logo.gif.

  • Does not parse http://www.novell.com.

[URL]: This section lists all URLs to be parsed. The rules of URL specification are similar to the ACLCheck module as follows:

www.novell.com               : Exact match
www.novell.com/contact/      : All files in contact directory, but 
                               not in subdirectories.
www.novell.com/contact/*     : All URLs starting with www.novell.com/
                               contact, including subdirectories of
                              contact.

[Replace]: The user can specify replacement pairs in this section. The string <<>> is used as a separator between the original string an the new string. The format is as follows:

[Replace]
<search string><<>><replacement string>

For example, to replace www.novell.com with support.novell.com, you would use the following format:

www.novell.com<<>>support.novell.com

All the lines after this Replacement section header are treated as replacement string pairs, so this should be the last section in the file.

Each replacement pair (including the last one) must be terminated with the end of the line.

17.2.2 Enabling the Custom Rewriter

You can enable the custom rewriter at the system console. The name of the module is rewrite.nlm. The configuration file or files can be supplied as command line parameters to the load command.

Filename restrictions: The rewrite.nlm module does not place any restrictions on the configuration filename format, but files that do not conform to DOS filename format (8.3) could cause errors while loading the file.

Load Time Command Line Parameters: The load command uses the following parameters.

rewrite [-s] -f filename [ -f filename]*

For example:

rewrite [-s] -f system/accell.rw -f etc/accel2.rw

The rewrite command supports the following parameters:

Parameter

Description

 
-s

Creates a separate screen for the rewrite filter. This parameter is optional

 
-f filename

Specifies the configuration file. This is the file from which configuration information is loaded. The user can specify as many configuration files as required. In the example above, accell.rw and accel2.rw are two configuration files in the specified format.

Runtime Console Commands

The following runtime console commands are also available to activate filters, stop filters, and to view current configuration information.

Command

Description

 
rwfilter unload filtername

Stops a filter (the filter name is as given in the configuration file).

 
rwfilter load configFile

Loads a filter configuration file.

 
rwfilter list

Lists all loaded rewriter filters by name.

 
rwfilter print filtername

Displays rewrite configuration information (the filter name is as given in the configuration). Printed information should be similar to the configuration file.

NOTE:The rwfilter list and rwfilter print filtername work only if you loaded rewrite.nlm with the -s option.

Configuring the Custom Rewriter to Start on Reboot

iChain 2.3 SP4 IR3 introduces a new way to automatically load custom rewriter configurations on reboot. Previously, custom rewriter commands were added to the end of the appstart.ncf file. As this file is replaced during the upgrade process, the commands to load the custom rewriter would have to be manually added after each update.

The appstart.ncf file now includes the following line:

sys:\etc\custom\customrw.ncf

If this file exists, the commands in it are executed automatically on reboot.

Additionally, all files in the sys:\etc\custom\ directory are added to the end of the current.nas file for backup and restore purposes. It is recommended that all custom rewriter configuration files be placed in this directory.

To have the custom rewriter automatically start when you reboot iChain, put the following line in the sys:\etc\custom\customrw.ncf file:

load rewrite -f filename

Replace filename with the path and name of your configuration file.

Multiple configuration files can be specified as follows.

load rewrite -f file1 -f file2 -f file3

The optional -s parameter can also be specified to create a separate rewrite filter screen.

If you are using a build of iChain prior to 2.3.329c (iChain 2.3 SP4 IR3), put the commands to load the custom rewriter files at the end of the sys:\system\appstart.ncf file. Because this file is replaced during the upgrade process, you need to manually add these modifications after each update.

17.2.3 Replacement Rules

The following are simple rules that the iChain rewrite filter uses:

  • String replacement is done as a single pass.

  • String replacement is not performed recursively. For example:

    [Replace]
DOG<<>>CAT
A<<>>O

    If the original string is DOG, the rewritten string is CAT. That is, only one replacement will occur (CAT will not be further replaced with COT).

  • Because string replacement is done in one pass, the string that matches first takes precedence. For example:

    [Replace]
ABC<<>>XYZ
BCDEF<<>>PQRSTUVWXYZ

    If the original string is ABCDEFGH, the replaced string is XYZDEFGH.

  • If two user-specified strings match the data portion, the original string of longer length is used for replacement except in cases detailed above. For example:

    [Replace]
ABC<<>>XYZ
ABCDEF<<>>PQRSTUVWXYZ

    If the original string is ABCDEFGH, the replaced string is PQRSTUVWXYZGH.

  • The rewrite filter module, rewrite.nlm, applies only one matching filter (each configuration filter file constitutes a filter) for a request. If multiple filters match a request URL, the matching filter that was configured most recently is used for data parsing.