The WebSiphon 2 Package
After downloading and decompressing the download, you should have a folder which looks similar to:
figure: WS2 download package contents.
By installing and using WebSiphon 2, you agree to be bound by the terms of our licensing which are outlined in the "License Agreement" file included in the distribution. If you have any questions about the agreement, or wish to offer a suggestion of improvement, please contact Purity Software directly.
The "Version History" file provides a glimpse into the many stages of evolution which has led to the current incarnation, including changes applied to the most recent release.
Choose an Installation Type
WebSiphon 2 supports two different types of installations:
- an external ACGI application; or
- an W*API-compliant plug-in library.
There are features and limitations unique to each installation type which should be considered:
- the ACGI runs as an external process, with its own memory space; whereas the plug-in version is loaded as part of the web server process, and shares memory space with the web server and any other installed server plug-ins.
- the plug-in version is significantly faster in operation than the ACGI application, as there is no overhead introduced by need for inter-process communication (via Apple Events) required between the web server and WebSiphon with each request.
- as an external process, the ACGI can be scripted to restart the web server remotely or execute other scripts arbitrarily if for some reason the web server process itself has failed; however, the plug-in cannot escape the grips of failure if the web server process fails.
- the ACGI version can accept incoming requests from Apple Script, Frontier or other environments which support Apple Events; the plug-in cannot receive event messages directly.
- in most cases the ACGI version will not work with POST arguments and HTTP file uploads beyond 32k in size (actually, a bit less due to variable data in the HTTP request and the overhead imposed by the Apple Event messenging architecture itself), due to lack of current support from most web server brands.
If your server supports it, the WebSiphon ACGI can receive large POST arguments using multiple ReadHTTPData events to read the request data in chunks and overcome any size limitations; the plug-in version does not suffer from arbitrary size contraints in working with POST data.
Recommended Installation
In most launch scenarios and if your server supports W*API, we recommend using the plug-in version. The speed gained by embedding WebSiphon as a plug-in library, coupled with able choice in using core features like file upload without limitations in your applications, provides an ideal web development platform.
However, WebSiphon is also quite capable as an external ACGI application and it shouldn't be discarded as an inferior configuration. In some integration scenarios the unique benefits offered by the external application outweigh those offered by the plug-in. Choice is good.
Copy Files to the Server
Once you have decided on an installation path, the time has come to copy the required runtime binary and supporting data files to the web server:
- ACGI Installation
- Copy both the "WebSiphon.acgi" application and the "WebSiphon Data" folder into the web server's "cgi-bin" directory.
- W*API Plug-in Installation
- Copy the "WebSiphon Plug-in" library and the "WebSiphon Data" folder into the web server's "Plug-ins" directory. Both of the "WSThreadsHub" and "MSL_All_PPC.Shlb" support libraries should be placed (copied) in the same directory as the web server application itself.
The "WSThreadsHub" and "MSL_All_PPC.Shlb" support libraries are only required by the plug-in installation, and as such they are ignored by the ACGI application if present.
Although it is technically possible to run both the ACGI and plug-in at the same time, this is not a "supported" system configuration. With that said if you choose to consider this route, it is important that each installation's "WebSiphon Data" folder is properly encapsulated and kept separate from the other.
Secure all WebSiphon Data Files
There are a few installation-related security considerations which require attention prior to continuing:
- Secure the "WebSiphon Data" folder
- Define a security realm and any other barriers necessary to insure that it is impossible to access files within the "WebSiphon Data" folder using any network service enabled on the web server. This includes FTP, AFP, or any other service.
WebSiphon and installed add-on libraries use this directory as a general repository for core environment settings and other preferences data, including private data like your serial registration key, the global data file, and Verona database tables.
For specific descriptions of each of the supporting files which ship with the default WebSiphon 2 package, see the Support Files section below.
- Secure the "/pi_admin.ws" script
- Define a security realm to insure that only admin users can access WebSiphon's web-based administration script. It is located in the main "Templates" folder, and is completely customizable as the implementation is written in SiphonScript.
Before you choose to continue with configuring your WebSiphon installation without first applying the above protections to your server, consider that any user connected to the hosting network (in most cases, the entire Internet) could potentially download your serial number or other private data. Depending on your hosting scenario and visibility this could be viewed as a vulnerability or benign detail. Above all else, use and exercise appropriate judgment with this knowledge in making this assessment.
Runtime Licensing Options
WebSiphon will operate for a specified period of time, depending on the which runtime licensing option is utilized:
- 2-Hour Demonstration
- by default and without configuration, the demonstration mode allows processing requests using WebSiphon for two hours at a given time. After two hours, any requests will return a runtime error indicating the demonstration period has lapsed.
- 30-Day Evaluation Key
- a 30-day demonstration key may be obtained from the Purity web site which extends the default runtime period.
- Extended Runtime Key
- If you require a more creative approach to licensing in order to complete your development goals, please contact Purity directly for assistance. Extended development keys are available for projects which require an arbitrarily defined usage license.
- Permanent Owner Key
- If you have already purchased a permanent WebSiphon license, we extend a gracious and most sincere "Thank you" for your support! Your permanent owner serial key was sent to you along with the details of the order transaction.
If you haven't yet purchased WebSiphon, please consider (not later, impulse decisions are best) buying a copy or three! Not only does your purchase vote your interest and support for independent software -- it'll make our day; and we really enjoy food and a drink from time to time!
- Non-Commercial Application Key
- If you are using WebSiphon to develop and/or host a non-commercial application, you may be elegible for a free permanent license key to support your project. See the Purity web site for details on obtaining a non-commercial owner license.
Registering a Serial Key
When the WebSiphon environment is initialized without a valid serial key installed, the server will beep and automatically enter the 2-hour demonstration mode. Once you have obtained a serial key, whether it be temporary or permanent, it must be installed to enable an extended runtime period.
There are three different methods of configuring WebSiphon's runtime settings, each of which allow serial key registration:
- Using the ACGI application
- Choose "Register..." available under the Edit menu to register a serial key.
WebSiphon's core environment preferences and add-on library preferences are configured using their respective commands also available under the Edit menu. Some library settings such as those which manage secured and automated server authentications in CommerceLib, FileMakerLib, and VeronaLib inherently must be configured using the WebSiphon ACGI application over other methods.
- Using the web-based admin
- Connect to /pi_admin.ws to enter a serial key or manage WebSiphon's core environment preferences, as well as preferences for select add-on libraries (given special exceptions outlined above; see note in ACGI section).
- Manually, using a text editor
- Located in the "WebSiphon Data" folder, the "WebSiphon Prefs" file is a text file which may be edited manually using any standard text editor. It is important the file format integrity is maintained, and edits shouldn't be applied while the WebSiphon process is active. It is also not a good idea to edit this file unless you know what you are doing.
For further information on all available WebSiphon preferences, they are covered in detail in the Prefs section of the documentation.
Configuring the Web Server
The web server must be informed of what types of requests should be routed to, and thus processed by WebSiphon. This is done by defining a web server action which points to either the ACGI or plug-in, and then assigning specific triggers (such as a particular suffix mapping, or a special runtime request like an error or no access condition) which invoke the action. This process is only slightly different with each installation type.
The following instructions are generalized and apply to most server brands:
- Using the ACGI application
- Define an action named "SIPHON_CGI" (or something of your choosing which identifies WebSiphon as the target) whose path points to the location of the "WebSiphon.acgi" application. For most server installations this will be "cgi-bin:WebSiphon.acgi"; or perhaps the same with "/" instead of colon characters in the path string.
Next, define a suffix mapping which triggers the SIPHON_CGI action. The traditional convention for scripts written to be processed with WebSiphon is to use ".ws" to identify scripts and ".t" for substitution templates. Regardless of which suffix mapping triggers you choose, the default file type should be set as "TEXT", file creator set to the wildcard "*" character, and "text/html" as the MIME type.
- Using the W*API plug-in
- When you install the plug-in version of WebSiphon, the file suffix mapping ".ws" is automatically defined for you and assigned to the SIPHON_PI plug-in action. Additional suffix mapping triggers are defined as described in the ACGI section above.
For specific instructions on configuring WebSiphon for use with a specific server brand, see:
Serving with WebSiphon
If you have defined the suffix mapping ".ws" to be processed by WebSiphon, the request /mantis/test.ws will return the runtime output of the script named in the URL.
The actual "test.ws" file may exist in either of two locations on disk:
- at the web location /mantis/test.ws; or
- in the "WebSiphon Data:Templates" folder
The script which is run (executed) by WebSiphon is located according to a standard and logically defined file-finding algorithm.
Ready to find out more about using WebSiphon?
- move along to the Getting Started section to learn more about using WebSiphon; or
- continue with further details about configuring WebSiphon's various runtime and built-in library settings in the Prefs section.