User's Guide
Using NetCloak with Other Tools
Contents
|
Version 3.1 User's Guide |
Using NetCloak with Other Tools |
Previous |
Next Contents |
Sometimes it is useful to use NetCloak in conjunction with another server add-on tool to process a single request. For example, you might have a page that is generated by a CGI linked to a database, but would like to include NetCloak commands in that page. This is called "CGI Chaining", and is made possible by NetCloak's ability to call other plug-ins or CGI applications.
NetCloak can call other CGIs or plug-ins in one of two ways, using either the EXEC command, or by creating a suffix mapping so that requests for a specified file type are automatically routed through NetCloak to a "back-end" CGI.
The EXEC_CGI command is useful when you want to run more than one additional CGI for a particular page, or when you write a CGI that returns just a part of a page. Similarly, EXEC_PIXO can be used to insert the output of many third party plug-ins. For example, you could write an AppleScript CGI that generated some random phrase to be inserted into your HTML page. Instead of returning an entire page (HTTP header and all), your script could return only the phrase it was written to create. The results of your script would then be read and inserted into the page as the page is processed by NetCloak. Any NetCloak commands in the results from the CGI will also be processed by NetCloak. For specifics of using the EXEC_CGI and EXEC_PIXO commands see the Reference Guide.
In addition to executing a CGI or plug-in as simply one part of an entire page, NetCloak can also accept entire pages generated by other CGIs and parse the NetCloak commands that appear in the resulting page. For example, if you wanted to include NetCloak commands within a Lasso response page, you would set up Lasso as a "back-end" to NetCloak.
When using the NetCloak plug-in, you may also make requests to other plug-ins that conform to the PIXO standard for inter-plug-in communication. In this case, the entry in the NetCloak.bsm file looks like this:
.NQRY TANGO_PIXO
where .NQRY is the file suffix that is mapped to the plug-in, and TANGO_PIXO is the name of the PIXO service registered by the plug-in (in this example, by the Tango 2.x plug-in). Check with the vendor of your other WebSTAR API plug-ins to see if they support PIXO. If they do, they can provide you with the exact name of their PIXO service.
When a request comes in to the web server and is dispatched to NetCloak, NetCloak checks to see if the file should be handled by another CGI or plug-in. If so, NetCloak immediately passes the request off to the appropriate process. The back-end process handles the request normally, but instead of returning the response page to your web server, it returns the response page to NetCloak. NetCloak then receives the page, processes any NetCloak commands that appear in the page and returns the final result to the web server, which sends the response to the client.
Figure 1: Flow of back-end CGI requests from the browser to the back-end CGI through NetCloak.
To set up a back-end CGI or plug-in, you must:
1. Make sure that the action that defines how your web server is going to handle the request points to NetCloak. For example, Lasso files usually end in ".las". To use Lasso as a back-end process, the suffix ".las" must use NetCloak for processing. Note that the web server will be sending these requests to NetCloak, not the CGI being back-ended! All CGI actions that will be cloaked must be referred directly from the web server to NetCloak.
2. Add a line to the NetCloak.bsm file. BSM stands for Back-end Suffix Mappings. This file tells NetCloak where to send requests that end with a particular suffix. It is made up of a file suffix (beginning with a period) and then the name of and path to the CGI application or plug-in to be called. Here is an example .bsm file:
.Q :Tango.acgi
.RSP :Responder.cgi
In this case, URLs with a suffix of .Q will be sent to Tango.acgi, and those ending in .RSP will be sent to Responder.cgi. The pathnames must be relative to the Root folder, and begin with a colon or slash.
Again, note that in your web server software, all of these suffix mappings should be directed to NetCloak so that NetCloak can hand off the request and then process the results.
A few additional notes:
When you give NetCloak the name of a CGI to execute in the .BSM file, the filename must be that of the actual application. The filename cannot be a file that is to be processed by an application or an alias to the CGI. You must tell NetCloak the full, exact name of the CGI application to be executed.
If the CGI is not in the same folder as NetCloak, you must specify a pathname for the CGI. Like aliases, pathnames in the NetCloak.bsm file must be paths relative to the root folder configured in NetCloak, and must start with a slash or colon. File and folder names in the pathname may be separated by slashes or colons.
You may use the .BSM file to specify up to thirty-two back-end processes.
Because of the extra overhead involved, back-ending CGIs can cause a noticeable decrease in performance on your server for pages served from a back-end CGI. We recommend that you only use back-end CGIs when needed. If another CGI does not require the use of NetCloak commands, don't set it up as a back-end CGI.
URLs that call CGIs by referring to them directly can be run through NetCloak without setting up a line in the .BSM file. Set your web server software to send all .CGI or .ACGI requests to NetCloak and it will automatically pass these URL requests to the specified CGI application and process the results.
Query or Path arguments specified in the URL will be preserved when NetCloak calls the back-end CGI, up to a maximum of 1024 characters. Post arguments are preserved up to a limit of 24Kb. This limit is the same as in WebSTAR.
If the error file setting of your web server is set to use a CGI, NetCloak will automatically route invalid requests to it and process any NetCloak commands in the page returned by the error CGI.
If you have trouble setting up a CGI as a back-end CGI, make sure that the CGI executes correctly by itself first. Set up your web server to call it directly, without going through NetCloak. If that doesn't help solve the problem, try temporarily replacing the CGI with the "Responder.cgi" application. Responder is handy because it shows you exactly what is being sent to the CGI. Move the CGI you are trying to back-end and copy and rename Responder in its place. If Responder works as the back-end CGI, then chances are good that your set-up is correct. If Responder doesn't return a meaningful page, then go back and check your web server and ".BSM" settings. You can download Responder from the Maxum Web site at www.maxum.com.
You may also need to change settings in the CGI you are attempting to run as a back-end. Some CGIs require configuration changes to operate properly as a back-end to NetCloak. Tango is a notable example.
| Copyright © 1996-2000 Maxum Development Corporation http://www.maxum.com/ |
Previous |
Next Contents |