IPAD 1.5 Features
IPAD Version 1.5 is a major upgrade with the following new features:
Last Updated 12/17/1996
This file, README.DOC, serves to present information about the product which is not reflected in the IPAD documentation. This includes documentation errors, additions, and clarifications. PLEASE TAKE THE TIME NOW TO READ THROUGH THIS FILE.
WHAT'S NEW IN VERSION 1.5
IPAD version 1.5 contains the following new features:
Full Frame Relay Support
- 100% Frame Relay Support. Multi-PVC Frame Relay support enables the IPAD to plug directly into all formats of Frame Relay eliminating the need for a separate FRAD or Frame Relay Router. The Multi-PVC capability allows up to 11 leased lines per single V.35 sync port. See Chapter 3 of your IPAD manual for more details.
New E-mail Capabilities
- E-mail Responder. An new e-mail responder using the RESP command in the MAIL_AUTH file. RESP returns a text file in response to any message sent to a specified address. See Chapter 6 for details.
- E-mail Redirector. Version 1.5 adds active forwarding at the SMTP level with the new REDIR command in the MAIL_AUTH file. REDIR allows messages messages destined for one e-mail address to be directed to a different email address. Wildcards easy aliasing large groups of addresses. See Chapter 6 for details.
- POP3 Mail Limits. You may now specify maximum byte limits for POP3 mailboxes both globally and on a user-by-user basis. See Chapter 6 and Appendix A under the SMTP command.
- ESMTP Support. The IPAD now supports "Extended" SMTP which exchanges more information about each message prior to transport. A primary benefit of ESMTP is that a message which is too large for a POP email box does not have to be transported and then discarded.
- POP Mailbox Indexing. POP3 mailboxes are now automatically indexed, allowing for rapid mail retrieval. No more long delays when connecting to a mailbox with very large messages or a large number of messages.
- STAT SMTP Enhancement. The "stat smtp" command will now list any messages in the \BAD directory (denoting their status with a "B" prefix). This allows easily detecting when mail routing problems are shunting mail to this directory. The new console command "stat smtp bad" will list only the bad message directory.
- E-mail Directory Cleanup. Version 1.5 performs much more e-mail sub-directory cleanup on shutdown and startup, eliminating stranded email files in nearly all cases.
- Miscellaneous SMTP Enhancements. Version 1.5 adds several SMTP enhancements which make e-mail more robust. These include:
- SMTP receiver now will add the Date:, From:, and Message-Id: lines to an incoming message header if they are absent in what was received. This allows the IPAD to "fix" messages that some clients send that are incorrect, allowing that mail to go through.
- Many error and validity checks have been added to the SMTP email receive logic so that Version 1.5 will properly handle many mal-formed messages and mal-conducted SMTP sessions allowing mail to go through even when the calling client is misbehaving.
- Version 1.5 now adds the IP address of the calling SMTP client as a comment on the "from" portion of the "Received:" email path tracing line in the received message. This allows far better detection and tracing of "spoofed" messages.
New Dial-up Enhancements
- Off-Hook. The new DOWN=OFF_HOOK keyword on the ANSWER statement will cause Version 1.5 to take a modem off-hook when the IPAD (or line) is shut down, busying out the phone line instead of allowing it to ring without answering. See Appendix A of your IPAD manual.
- Modem Detection. Version 1.5 has more robust modem handling. With this improved modem string handling, automatic modem detection (and logging of disconnect reason) has been disabled. If you wish to re-enable it, you must add the "-m" switch to the IPAD command line such as:
- Digiboard PC/xEM series smart card support. This support allows the IPAD to run 32 serial lines at a full 115k (as opposed to the 57.6k rating of the dumb serial ports). This support will allow full speed use of the coming higher speed modems. See the "Digiboard xEM Smart Card Support" section of this document.
- DNS Server Sessions. The maximum simultaneous DNS server sessions has been raised to 40 from its previous limit of 20, allowing DNS to appear faster under heavy load.
Local Console Enhancements
- Local Console Size and Windows. You may now re-size the IPAD's local console into 25, 28, 43, and 50 line modes to view more data at once. Additionally, a new data window is available to present the TCP/IP Interface status in a single location. You may specify the presence and size of the Terminal, and Client/Server windows, as well as the new Interfaces window. Refer to Appendix A under the SYSTEM statement and Appendix B.
- Summary Data. The local console lower window now chooses more information to display based upon the IPAD's configuration and the number of screen lines chosen. This new information includes session and connect information for dial-up, telnet, and WWW connections. The
stat actcommand always shows all of these new statistics including POP3 connects and time spent in the POP3 server.
- Special Exit on Fatal Configuration Errors. If there is a fatal error in the IPAD.CTL file, the IPAD will now exit with the errorlevel 250, allowing special handing in the startup batch file for reliable remote operation. The IPAD wait up to 10 seconds for a key press before exiting, and does not clear the screen on exit, so no information is lost during attended operation.
- New Time and Date commands. Version 1.5 allows you to read and/or change the IPAD's time and date from the local console, telnet maintenance server, or supervisor terminal server using the
datecommands, respectively. See Appendix B.
- Enhanced Packet Driver Interface Commands. The PACKET interface definition command in IPAD.CTL is now superseded by new interface definition commands for each supported type of interface. These new statements are ETHERNET, TOKEN_RING, FRAME_RELAY, and SYNC_PPP and are discussed in Chapter 3 and Appendix A.
Note: Version 1.5 retains the PACKET command for backward compatibility, and it continues to operate as it did in Version 1.x. However it is no longer documented and to use the new features such as Frame Relay these commands will need to be converted to the new syntax.
- Both packet driver (e.g.,ETHERNET, SYNC_PPP) and asynchronous interface statements (e.g.,PPP_SLIP, TERMINAL) have been enhanced to configure routes and defaults more robustly. Specifically, these enhancements include:
- <IP_Address>/<bits> notation is now supported for the IP_ADDRESS keyword as an alternative to specifying NETMASK=nn.nn.nn.nn.
- The BCAST_ADR= now defaults correctly. Since this part of the interface definition wasn't used in Version 1.12, the fact that it defaulted improperly was not a problem. But now it defaults correctly.
- Version 1.5 now puts a warning message in the system log if an IP address and netmask on this interface generate the same static route as was generated by another interface. Previously a human had to discover this error and correct it to obtain proper operation.
- Temp Files. The IPAD now clears any stranded temp files from the temp file directory on boot-up, preventing their build-up with reset reboots or power outage shutdowns.
ADDITIONS TO THE VERSION 1.5 MANUAL
The following additions to SMTP email and the WWW_LITE server are not documented in the Version 1.5 manual:
SMTP MAIL PROCESSING
The Version 1.5 SMTP mail scanner has been re-written to send large amounts of mail up to 10 times faster than before. You don't have to change anything in your email configuration to gain the advantage of this increase in performance, but there is one new option on the SMTP statement to allow you to adjust the number of simultaneous DNS lookups email will do to overlap scanning and sending. The syntax of this option is:
- <num> Specifies the maximum number of simultaneous DNS lookups to perform during an email scan and is in the range 1 to 10. The default if this option is not specified is 3 which is optimal for most cases.
CAUTION: If you set this value larger than 5, you run the risk of overusing your IPAD's DNS server (causing DNS request timeouts and slow DNS response) if you are also having the DNS server used by callers. At its maximum value, the SMTP server can generate as many as 25 to 30 DNS server sessions at peak (given how complex the lookups are and what is cached at the time). This would only allow 15 caller DNS hits to be available during large mail loading times.
DIGIBOARD XEM SMART CARD SUPPORT
Version 1.5 now supports the use of the Digiboard PC/XEM smart serial cards for up to 32 lines of serial I/O. The following IPAD.CTL file command syntax changes allow you to configure these cards:
- For the MULTIPORT command:
MULTIPORT IRQ=<n> TYPE=DIGI_XEM STATUS=<xxx> [ADDR=hhhh]
<n> indicates the IRQ the PC/XEM host card is set for.
<xxx> is the address of the PC/XEM status port (eSoft recommends setting this port to 0x104).
The optional ADDR=hhhh command will generally not be required. When the IPAD boots, it attempts to locate address space for the memory mapped portion of the PC/XEM host card automatically. Only if this fails, and eSoft tech support indicates you should use it should this option be needed. If used, it tells the IPAD where to map the physical 32k memory space used by the PC/XEM host card.
Note: The LINES= option of the MULTIPORT card SHOULD NOT BE USED when TYPE=DIGI_XEM is specified.
- For serial line definition (PPP_SLIP, PPP, SLIP, or TERMINAL commands):
The PORT=<nn> option on these lines should be in the range 1-32, indicating the physical port number this line connects to on the PC/XEM port box. 1-16 for the first box, 17-32 for the second port box. This number is DECIMAL, not hex for PC/XEM ports.
Note: Unlike with dumb Digiboards, the PC/XEM ports do not have the be defined in order or contiguously. Any order is fine, and you may leave "holes" if you wish.
- Placement of the PC/XEM BIOS and FEP programs on disk:
The final step to using the PC/XEM cards is to copy the files "SXBIOS.BIN" and "SXFEP.BIN" into the IPAD startup directory. These files are loaded into the PC/Xem board when the IPAD starts up, and the IPAD won't start without them being present if you use PC/XEM cards. These files are located under the \XEM directory on the second IPAD distribution diskette.
Note: The IPAD startup takes about 5-10 seconds longer when PC/XEM cards are used because of the time taken to load the FEP/OS into the host adapter.
WWW LITE LOGGING, AUTHENTICATION, FORMS HANDLING, AND COUNTER CGI
The IPAD's web server lite now processes forms, includes a counter CGI, handles authentication, and may be configured to optionally write web-related data to a separate log file in the common log format.
Here are the details on each of these new Version 1.5 WWW server features:
WWW SERVER AUTHENTICATION
For some web applications, you may wish to create a "closed server" which requires a name and password to access. Version 1.5 allows you to limit access on a server-by-server basis by adding the "AUTHENTICATION=" keyword to a WWW_LITE web server IPAD.CTL configuration command.
The syntax for the authorization keyword is as follows:
This is any text name you wish to give this server. It is used by the browser to indicate to the user that the name and password will only apply to this realm. Therefore, the string here should be unique to all web servers you require authorization for.
The name specifies the text name that the user will have to enter to access any page on this web server.
The password specifies the password associated with this name.
; Define a web server at IP address 192.168.143.201 with a name
; of "docs.example.com" and a home directory of C:\WWW\DOCS.
; In order to access pages within the Example_Docs realm, the user
; must specify "Author" and "SeCreT" as the name and password.
WWW_LITE IP_ADDRESS=192.168.143.201 NAME=docs.example.com &
WWW COMMON LOG FORMAT LOGGING
Version 1.5 allows you to log web server requests to a separate log file in the CERN Common Log Format. This allows you to use many of the web log analysis programs available that use this standard WWW logging format as input. If this log is not activated, all requests go into the system log in IPAD format. If this logging is activated, then no logging of web server activity will appear in the IPAD system log.
The syntax for the common log format web log is:
WWW_LOG <filename> [RFC931]
The full path and filename for the WWW common log format log.
This optional parameter is used to make the log format fit the strict RFC 931 format. This causes the second field to always be "-" instead of the local server IP address or name (if specified using the NAME= option). Some analyzers expect this field to always be a dash, and this option will satisfy them.
; file in CERN common log format, instead of the IPAD system log file.
The CERN common log format is a text file where each line contains a record that is defined as follows:
<remotehost> <server> <authuser> [<date>] "<request>" <status> <bytes>
Where these fields have the following meaning:
IP number of remote system making the request.
<server> Dash (-) if RFC931 option used, otherwise this field will have the IP number or NAME=<name> of the IPAD WWW_LITE server that was contacted for this request.
<authuser> Username used if authentication occurred, "-" otherwise.
[<date>] Date and time of the request with offset from GMT indicated. Format of this date is: [dd/mon/yyyy:hh:mm:ss offset] NOTE: Offset from GMT derived from the IPAD's Time Zone setting.
"<request>" The HTTP request line exactly as it came from the client.
<status> The HTTP status code returned to the client by the server.
<bytes> The content-length of the document transferred.
WWW HIT COUNTER CGI
Version 1.5 implements a "page hit" counter CGI which records the number of "hits" a web page receives. While this data can be useful to you to know how much usage a page receives, it's also informative to show the user the same information embedded in a page. The IPAD allows an unlimited number of page hit counters.
You've likely seen web pages that notify you with a message such as:
"This Site Accessed 0027 times"
This is done using a counter CGI that may be used in any HTML page that you choose. Each time the CGI is accessed, it increases a counter in a text file and returns the counter data to the user's browser in the XBM format ("Content-type: image/x-xbitmap").
Current versions of Netscape Navigator and Microsoft Internet Explorer display this graphic format slightly differently if it is simply inserted in the text so it is recommended that you define a table or frame to put the counter value in for consistency across all browsers.
The counter CGI is used inside an <IMG SRC> HTML tag with the following URL syntax:
The counter name. This is the name of the counter file, without the .CTR extension, kept in the /cgi-ipad/ sub-directory of this web server's HOME= directory. If either the /cgi-ipad directory or counter file do not exist, they are automatically created under the web server's home path. In the event that the IPAD is unable to create either the directory or counter file, the CGI call will return a "404 Not Found" error message.
Since each counter is named separately, an unlimited number of page counters may be used.
Format the counter image using any combination of the following letters:
- r = Reverse video d Double height characters. Makes numbers twice as tall.
Additionally, only ONE of the following letters may be used:
- c = Characters centered vertically with 3 leading and trailing blank scan lines.
- b = Character at bottom of vertical field with 6 leading blank scan lines.
- t = Character at top of vertical field with 6 trailing blank scan lines.
- s = Vertical field has only active character scan lines. This is 10 lines normally, 20 lines if "d" given.
The default <image> value is 'c'.
Specifies the number of digits to display in the counter and is in the range of 0 to 10. The default value is 4.
If this value is set to 0, the CGI adjusts the image to not display any leading zeros. The image will grow as needed from 1 to 10 digits based on the value of the counter.
<b>You are visitor <IMG src=/cgi-ipad/counter.exe/ctr1?digits=6></b>
WWW FORMS HANDLING CGI
With Version 1.5, the IPAD can now directly process WWW forms responses. This feature allows you to save form data as entered by users into a variety of different file formats. Note: The IPAD's handling of forms has been made Polyform compatible and is a sub-set of what the full O'Reilly Polyform CGI allows, letting you use the Polyform program to generate forms for the IPAD's WWW_LITE server.
Configuring form processing on the IPAD consists of three steps:
- Enabling form processing on the desired web server. This is done by specifying the form processing control file using the FORMS=<inifile> keyword on the IPAD.CTL WWW_LITE command.
- Configuring the forms processing .INI file. This file tells the IPAD how each form specified should be processed.
- Creating the HTML file that contains the form.
We'll Now look at each of these three steps in detail:
Step 1. Enabling Form Processing
To enable form processing, specify the form processing .INI configuration file using the "FORMS=" keyword on the WWW_LITE statement. This file may reside anywhere within the IPAD's disk space. Note: If you wish to place the .INI file in the WWW_LITE server's file space, you should place it in the new /cgi-ipad/ directory beneath the web server's HOME= directory, since the WWW server cannot access files in this area and thus any file is secure there.
|; Define a web server at IP address 126.96.36.199 with a name
; of "info.example.com" and a home directory of C:\WWW\INFO.
; The form processing file C:\FORMS\INFO.INI WWW_LITE IP_ADDRESS=188.8.131.52 NAME=docs.example.com &
Step 2. Configure the form processing configuration file
Next, you must specify how the IPAD should process each form you want to use. You do this by editing the form configuration file you specified earlier using the "FORMS=" keyword. All forms for a single web server are configured in this .INI file.
The syntax for the FORMS= .INI file is as follows:
[<formname>] SendURL=<return_URL> Archive=<file> OutputStyle=TEXT|COMMA|RAW
Where the meaning of each field is as follows:
This is the name of the form as it appears in the form Universal Resource Locator (URL). The URL is in detail explained later in this document. At this time, however, it is important to know that the <formname> is the final piece on the URL.
For example, with the URL:
the form name is "form_1". Therefore, the form name field as it appears for this form would be: [form_1]
The <formname> is not case sensitive either in the URL or this file, so "Form_1" is the same as "form_1", etc.
After a form is processed, the IPAD can return a file back to the user. Typically this is an HTML document to notify the user that the form was accepted. This may be any URL local to this web server, a URL on any of the other web servers on the IPAD, or a URL on any other web server available anywhere on the Internet.
The Archive field specifies the file where form data will be saved. The data from each new form response is appended to the end of this file. This file may reside anywhere in the IPAD's file space, and is frequently placed on a shared file server so that an off-line program elsewhere on the LAN may process it while the IPAD is running. If this file does not exist, the IPAD will create it with the next form response.
This field specifies the format of the output that the web server writes to the "Archive=" file. These formats are explained in detail later in this section. Briefly, the types are as follows:
TEXT Field names and data are displayed on individual lines, suitable for human reading.
COMMA Field data is stored in a comma delimited format, suitable for importing by many types of databases or spreadsheets.
RAW All information from a submitted form are stored on a single line as received from the client's web browser.
Any extra field names and parameters in the form processing .INI file are ignored. This allows the IPAD's web lite server to use Polyform's POLYFORM.INI file directly. Any fields or actions not detailed in this section are ignored by the IPAD.
|; Define a configuration for processing two forms named
; "Form_2" Form_1 stores form data into the file C:\IPAD\FORMS\FORM1.TXT
; in text format, while Form_2 stores data in comma delimited format into
; the file C:\IPAD\FORMS\FORM2.DAT. The file that the web server returns
; for Form_1 is the file "f1resp.htm" in the forms directory RELATIVE to
; this web server's home directory, and the response for Form_2 is the
; file "f2resp.htm".
Step 3. Create the HTML code containing the form
Finally, create the HTML document containing the form to be processed. It is beyond the scope of this document to explain forms in detail, but briefly, a form consists of the following tags:
<FORM ACTION="<URL>" METHOD="POST"|"GET"> ... </FORM>
This is the URL of the form CGI and form reference as described previously. The URL's syntax is:
This is the IP address or domain name of the web server.
This field indicates to the IPAD's web server that a CGI process is desired. This path can be anything that begins with "/cgi-" and is normally "/cgi-ipad/". However, paths such as "/cgi-bin/" and "/cgi-win/" also work with the IPAD's web server, allowing use of programs that automatically generate forms that expect this to be the CGI program location.
Note: Unlike other web servers, the IPAD's web server does not do a "shell call" to an external CGI program. Thus there are no security issues in using the "pseudo-CGI" features in the IPAD.
This field specifies the name of the form CGI. With the IPAD's web server lite, ANY CGI program name with the word "form" within it works. Therefore, you could use names such as "form.exe", "polyform.exe", or even just "form". For example, the following URLs which use different variations of "form" are all equivalent:
Here you specify the form name as defined earlier in the FORMS= .INI processing file. This name is case in-sensitive.
CGI data may be submitted with either the POST or GET methods. There is no difference between how the IPAD will process either type, and you can choose either one at will.
|<!-- The following form specifies that the form
processing should be done at the site docs.example.com with the CGI name
"form" and form name "User_Data". -->
<FORM ACTION="http://docs.example.com/form/Form_1" METHOD=POST> ... </FORM>
Also, you will want to use <INPUT> tags inside of the <FORM> ... </FORM> tags. An INPUT tag has the following syntax:
<INPUT NAME="<name>" value="<value>" TYPE=<type>>
This specifies the name of the form data. This may be any text that you like. As explained later in the comma-delimited section you may wish to preface the name with a field number such as "1E-mail".
Here you may specify a "preloaded" value for the user such as "Type your e-mail address here!" This is the field where any data entered by the user will be returned to the web server.
This field specifies the type of data to be returned. The type you choose determines how the input element will be displayed in the user's browser. The available types are:
TEXT A text-box for entering strings of data. You may also specify the length of the data with the MAXLENGTH=<chars> keyword and the size of the box as displayed to the user with the size=<chars> keyword.
PASSWORD Another type of text-box, however, all data entered by the user is displayed to them with asterisks, preventing others from seeing the data they type in.
CHECKBOX This type specifies a checkbox that may have either an on or off value. An additional field for the <INPUT> tag with this type is CHECKED, which means that the box's value is on.
RADIO Like the checkbox, this displays a round circle that may either be on or off. The CHECKED keyword makes the radio button on to the user.
HIDDEN This data is hidden from the user's browser. It is used to pass data back to the form processor.
RESET This action displays a button and allows the user to reload the form data to its initial settings.
SUBMIT This is an action type that displays a button and causes the form data to be submitted to the web server.
IMAGE With this type, you may replace the SUBMIT button with any graphic file of your choosing.
Finally, you may mix any standard HTML tags inside the form to format the display as required. For a more exhaustive description of creating forms, consult an HTML reference guide.
The following HTML code uses the Form_1 form as defined previously to get a user's name and e-mail address:
<FORM METHOD="POST" ACTION="http://docs.example.com/cgi-ipad/form/Form_1">
<p>We'd appreciate it if you would give us your first name and e-mail address.
First name <INPUT NAME=Name TYPE=TEXT size=20><br>
E-mail address <INPUT NAME=E-mail TYPE=TEXT size=50><br>
<INPUT value="Here you go!" TYPE=SUBMIT>
Note: If you submit a form in an HTML file that is not defined in the server's FORMS= .INI file, a "404 file not found" error is returned by the web server.
Form Output File Formats
The IPAD allows you to save form data in three different formats:
- Comma delimited.
Text format appends a date/time header to the data and a trailer containing the text "Submitted by: <IP_address>" and a dashed line separator. The data itself is a series of lines which begin with the form's <INPUT NAME> field followed by the field's data. Each field is separated by a blank line from the next field so that a multi-line text block can be seen as a single field.
An example of output from the Form_1 field might look like the following:
|Date 11/25/96 Time 12:45 PM
Submitted by: 192.168.143.37
Comma Delimited Format
The comma delimited format allows for importing of form data into certain databases and spreadsheets. Because some forms fields (such as radio buttons) do not always have any response, and because form fields are not always sent by a browser in the order defined in the HTML file, the IPAD needs information to assure that each field is put in its proper comma delimited field position and also to properly report empty fields. This is done by prefixing each form input field NAME with a decimal number. This number indicates the position of this field in the comma delimited record. If the final field is always present (i.e. not radio button, etc.) then this is all you need to do.
If the final field is optional, then the IPAD needs to know the fixed number of fields and a special construct is used to define that by adding the following form variable:
<INPUT NAME="Count" value=<num> TYPE=HIDDEN>
This tells the IPAD that there are always <num> fields in the comma delimited output record. This special option won't be needed if you simply make sure that the final field (with its number) in your form is always present.
An example of an HTML file that uses the Count variable and numbered field names for comma delimited output is as follows:
<FORM METHOD="POST" ACTION="http://docs.example.com/cgi-ipad/form/More_Info">
Please complete all fields for which you have appropriate information:<br>
Contact name: <INPUT NAME="1Name" size=40><br>
Company, or organization name: <INPUT NAME="2Company" size=50><br>
<B>PLEASE CLICK ONE:</B> Do you run an IPAD?
<li><INPUT NAME="8IPAD" TYPE="radio" value="No IPAD"> No, I do not </li>
<li><INPUT NAME="8IPAD" TYPE="radio" value="Yes IPAD"> Yes, I run an IPAD</li>
To submit your information request, press this button:
<INPUT value="Submit Program Entry" TYPE=SUBMIT><br>
To clear the form, press this button: <INPUT value="Clear Form" TYPE=RESET >
The comma delimited output for this file might look like the following:
Note that the output for each form response is a single line.
If for some reason you can't process either the Text or Comma delimited format of Forms output, you can use the raw format. With this format, each form response will append a single ASCII line which is the URL encoded raw forms data response line from the browser. To use this you will need a program that can read such raw data and will have to refer to the proper RFC's to decode the line.
UNINTELLIGENT BOARD SUPPORT - DESKTOP MODELS ONLY
The manual now reflects unintelligent boards for the IPAD rackmount model. If you're using desktop models with unintelligent Digiboards as purchased through eSoft, you must use the following port addresses when configuring asynchronous ports.
Table 5-1a/Table 11-1a. Port numbers for two 16-port DigiBoards.
Table 5-1a/Table 11-1a. Port numbers for four 8-port DigiBoards.