Gibraltar

HTTP HTML/BGI Administration Tool ( HTMLA )

Note: Generally, this project is not being discussed under NDA with any accounts or third parties.
Should you require permission to discuss this with a particular organization outside the company,
please contact the author.

Revision: 0.4
Date: March 6,1996
Author(s): Philippe Choquier
Document: htmla.doc

Microsoft Confidential
1 Background
This specification describes the BGI based administrative tool for Microsoft Internet services. This tool
generates HTML documents and allow the configuration of the Microsoft W3, Gopher and FTP services
through any web browser.
It is exposed as a set of extension to the HTML format to query and update the status of services.
These extensions are used in scripts stored on the web server and interpreted by the htmla DLL to generate
HTML replies to queries received as URLs
2 Framework
All URL references will go to the HTML BGI DLL. An execution context will be provided by the path
contained after the ‘?’ character in the URL.
The characters before the first ‘/’ in the path will determine the service name : http, ftp, gopher or dir. The
“dir” services allow access to directory browsing functionalities, and is not an Internet service.
The characters between the first ‘/’ and ‘+’ ( if present ) will determine script name. The file name will be
constructed by concatenating the path of the DLL, the script name and the “.htr” extension.
All characters following ‘+’ ( if present ) will be stored in the “urlparam” variable ( see the variables
section below ), and will be typically be used to store an element reference ( see the discussion of
references in the verb section below ).

Ex:

http://www.gibraltar.com/scripts/htmla.dll?htttp/servprop

This will reference the servprop.htr script file stored in the same directory as htmla.dll

http://www.gibraltar.com/scripts/htmla.dll?htttp/servuser/list+11.0.0.1!255.255.255.255

This will reference the servuser/list.htr script file stored in the same directory as htmla.dll, with the
variable “urlparam” set to “11.0.0.1!255.255.255.255”
3 Syntax
The extended keywords described below cannot be nested, i.e. you cannot use a ‘<%’ construct while in
another.

3.1 BEGIN ITERATION

<%beginiteration loopvar%>

The begin/end iteration defines a loop block that will be repeated loopvar times. This is to be used with a
list, such as the IP access lists and the virtual root list. The loopvar variable should be the count associated
with each list ( see the variables section below for the definition of lists and counters ).

3.2 END ITERATION

<%enditeration%>

3.3 IF
<%if exp1 relop exp2%>
Exp1 and Exp2 can be either a variable name as defined in the “variables” section below, or a literal
numeric or string ( inside quotes ) value. In either case, the type of both expression must match.

The relop relational operator is defined as follow :

Operator Description
EQ equal
NE not equal
LT less than
GT greater than
LE less than or equal
GE greater than or equal
RF Reference ( for string only )

The if blocks can be nested.

The RF ( Reference ) relational operator tests for the occurrence of Exp2 inside Exp1, where Exp1 is
parsed as the result of a FORM HTML construct, i.e. tests for Exp2 being the target of an assignment.

3.4 ELIF
<%elif exp1 relop exp2%>
See the discussion for the “IF” statement above.

3.5 ELSE
<%else%>

3.6 ENDIF
<%endif%>

3.7 ONERROR
<%onerror LabelReference%>
Will transfer execution to the given label if any error occurs ( i.e. reqstatus becomes not 0 ).

3.8 GOTO
<%goto LabelReference%>
Transfer execution to the given label. Scanning for label is forward looking only : you can only goto a
label following your current location.

3.9 LABEL
<%label LabelReference%>
Define a label.

3.10 REDIRECT
<%redirect%>URL<%/redirect%>
The text defined by this construction will be used as a URL to redirect the web server to ( i.e. a
HSE_REQ_SEND_URL call will be issued with this text as a parameter ).

3.11 POST
<%post%>service_info?message_body<%/post%>
This is an internal redirection request, where service_info will be decoded as service “/” script file, and
message_body will be presented to the service as if a POST request had been used.
The htmla.dll will reprocess this request as if it came from a client. This is mostly usefull to link between
“dir” and Internet services.

3.12 Verbs reference

<%!VerbName[var[,var]*]%>
See the list of verbs in the verb section below.

3.13 Variable reference

<%VarName%>
See the list of variables in the variables section below.

3.14 Error Handling

Syntax errors, unknown variables, type mismatch, If nesting mismatch and other errors will update the
“reqstatus” variable. The erroneous statement will be ignored and processing will resume with the next
character. It is strongly suggested that the “onerror” statement be used to detect such errors.
4 Verbs
The verb names are case-sensitive.
All the verbs except “Update” deal with list of elements. Three basic operations are defined per list : add
an element, delete an element and set a specific element as the “default” element, used by subsequent
references to variables in this list. The delete and set position verbs are using an “element reference”,
which is a string uniquely identifying an element. This reference is returned by dereferencing a “unique-
ID” variable, defined per list ( see the description of variables below ).
Three list are defined : The Deny access list, the Grant access list and the Virtual directory list.

Name Parameter Description

AddDenyIpAccess None Add an element in the deny access list
DelDenyIpAccess IP element reference Delete an element in the deny access list
( <%ipdenyref%>, via
urlparam )
PosDenyIpAccess IP element reference Position on an element in the deny access list
( <%ipdenyref%>, via
urlparam )
SetDefaultIpAccessToDeny None Set the default to be deny access
To be used to change the default or to insure
that the default is set to Deny after a deletion in
the grant list that may cause this list to be
empty.
AddGrantIpAccess None Add an element in the grant access list
DelGrantIpAccess IP element reference Delete an element in the grant access list
( <%ipgrantref%>,
via urlparam )
PosGrantIpAccess IP element reference Position on an element in the grant access list
( <%ipgrantref%>,
via urlparam )
SetDefaultIpAccessToGrant None Set the default to be grant access
To be used to change the default or to insure
that the default is set to Grant after a deletion
in the deny list that may cause this list to be
empty.
DisconnectUser User ID Disconnect a user from the service
( <%enumuserid%>,
via urlparam )
DisconnectAll None Disconnect all users from the service
AddVirtDir None Add an element in the directory list
DelVirtDir Dir element reference Delete an element in the directory list
PosVirtDir Dir element reference Position on an element in the directory list
Clear Variable If the variable is a DWORD or a BOOL, its
value is set to 0 ( FALSE ). Necessary because
a Web Browser doesn’t transmit a checkbox
input type if it is not checked, so it is necessary
to set all checkbox variables to 0 before
processing a form action.
Update None Update all variables defined in this request ( to
be used with a FORM statement )
GetStatus None Updates the xxxstatus variables for internet
services ( e.g. httpstatus )
Directory browsing
GenerateDirList None Generates the “dir” service variables ( cf.
Variables, dir service below )
ValidateDir path Check If path is valid. Updated reqstatus on
 exit.
CreateDir path, directory_name Create directory_name in path, updates
reqstatus on exit

Verb execution will update the “reqstatus” variable, which will contains a numeric value giving the status
of the request. If the status is not zero the service configuration will not be updated.
This status can be used in the “onerror” andor “if” commands described above.
5 Variables
Variable names are case-insensitive.
All variables referencing a configuration structure as defined in inetcom.h or inetinfo.h is prefixed with
either “com” for INET_COM_CONFIG_INFO, “w3” for W3_CONFIG_INFO, “ftp” for
FTP_CONFIG_INFO, “gopher” for GOPHERD_CONFIG_INFO, “global” for
INET_INFO_GLOBAL_CONFIG_INFO.

All variables access will be rendered as an ASCII string. The type as defined in the following tables is to
be interpreted in the following way :
· String : returns an ASCII string
· DWORD : returns the ASCII representation of a DWORD.
· BOOL : can only returns “0” or “1”

5.1 HTTP, FTP & Gopher services

Name Type Description
reqstatus DWORD Status request ( see the error code section below for a list of values )
rpcstatus DWORD Status of the last RPC call. Typical errors : 5 ( access denied ), 1062
( service not started )
urlparam String The characters following the ‘+’ character in the URL, after skipping
the service name and the script name
servname String Service name ( “http”, “ftp”, “gopher” )
servid DWORD Numeric service ID : http is 4, ftp is 1, gopher is 2
remoteaddr String IP address of the client for the current request
hostname String Local host name as a fully qualified domain name if available, else as a
ASCII representation of the IP address.
Ipnulladdr String Address used by the admin server to fill an IP security list ( grant or
deny ) to indicates that this list contains exceptions, and that the default
access is the opposite of this list definition.
reqparam String Contains the request body ( usually the result of a HTML FORM ).
iter DWORD Current index while in a beginiteration construct ( 0 based )
htmlapath String From the W3SVC\Parameters\HtmlaPath::REG_SZ registry entry. This
allow the .htr files to be location independent.
httpstatus DWORD Status of the service : 0 if running, not 0 if not available
ftpstatus DWORD Status of the service : 0 if running, not 0 if not available
gopherstatus DWORD Status of the service : 0 if running, not 0 if not available
Common config
comconntimeout DWORD Connection timeout
commaxconn DWORD Maximum connections
comadminname String Service administrator name
comadminemail String Service administrator email
comservercomment String Server comment
LOGGING
enablelog BOOL 1 to enable logging
logtype DWORD 1 for file, 2 for SQL
enablenewlog BOOL 1 to automatically open new log
logperiod DWORD 1 daily, 2 weekly, 3 monthly, 4 yearly, 5 on file size
logdir String
logsize DWORD file size triggering new log file
logsrc String ODBC data source
logname String ODBC table
loguser String ODBC user name
logpw String ODBC password
invalidlogupdate DWORD 1 if update to file settings while in ODBC mode, 2 if update to ODBC
 while in file mode, 4 if modifications to log size while not in file size
mode.
Internet Config
loganon BOOL Log anonymous users
lognona BOOL Log non-anonymous users
anonun String Anonymous logon user name
anonpw String Anonymous logon password
authanon BOOL Authentication : allow anonymous
authbasic BOOL Authentication : allow basic
authnt BOOL Authentication : allow NT
sport DWORD Port number
Deny IP List
denyipcount DWORD Count of elements in the list
denyipaddr String IP Address of the current element in the deny list
denyipmask String IP subnet mask of the current element in the deny list
denyisipsingle BOOL 1 if the current element in the deny refers to a single computer ( mask is
all 1 )
Grant IP List
grantipcount DWORD Count of elements in the list
grantipaddr String IP Address of the current element in the grant list
grantipmask String IP subnet mask of the current element in the grant list
grantisipsingle BOOL 1 if the current element in the grant refers to a single computer ( mask
is all 1 )
IP List reference
ipdenyref String Reference to the current element in the deny list.
To be used in a URL to an update script ( referenced in the script by
urlparam, typically as a parameter to <%PosDenyIpAccess %>
ipgrantref String Reference to the current element in the grant list.
To be used in a URL to an update script ( referenced in the script by
urlparam, typically as a parameter to <%PosGrantIpAccess %>
Virtual roots
rootcount DWORD Count of elements in the list
rootname String Virtual root name
rootishome BOOL 1 if this virtual root is home directory
rootaddr String Optional IP address
rootdir String physical directory
rootisread BOOL 1 if mask includes read access
rootiswrite BOOL 1 if mask includes write access
rootisexec BOOL 1 if mask includes execute access
rootisssl BOOL 1 if requires SSL
rootacctname String Account to connect as
rootacctpw String password for account
rooterror DWORD reserved
Virtual root
reference
rootref String To be used in a URL to an update script ( referenced in the script by
urlparam, typically as a parameter to <%PosVirtDir %>
W3 config
w3dirbrowseenabled BOOL Directory browsing enabled
w3defaultfileenabled BOOL Default file enabled
w3defaultfile String Default file
w3ssienabled BOOL SSI enabled
w3ssiext String SSI extension
Gopher config
gophersite String Gopher site name
gopherorg String Organization name
gopherloc String Location of server
gophergeo String Geographical data
gopherlang String Language for server
FTP config
ftpallowanon BOOL Allow anonymous access
ftpallowguest BOOL Allow guest access
ftpannotdir BOOL Annotate directories
ftpanononly BOOL Allow anonymous access only
ftpexitmsg String Exit messag
ftpgreetmsg String welcome message
ftphomedir String Home directory
ftmaxclmsg String Maximum connection reached message
ftpmsdosdirout BOOL 1 if Directory listing style as ms-dos, 0 as unix
Global config
globalbandwidth DWORD Maximum network usage in KB/s
globalcache DWORD Global cache size
globalisbandwidthli BOOL 1 if the globalbandwidth field is enabled
mited
User enumeration Enumerate users currently connected to the service
enumusercount DWORD Connected user count
enumusername String User name
enumuseranon BOOL 1 if the user is logged in as anonymous
enumuseraddr String IP Host address
enumusertime DWORD User connection time ( in seconds )

Note that a .htr script is bound to one and only one service (HTTP, FTP, Gopher ) at a time. Access to
variables undefined for the current service will generate an error.
 5.2 Dir Service
Name Type Description
reqstatus DWORD Status request ( see the error code section below for a list of values )
urlparam String The characters following the ‘+’ character in the URL, after skipping
the service name and the script name
remoteaddr String IP address of the client for the current request
hostname String Local host name as a fully qualified domain name if available, else as a
ASCII representation of the IP address.
reqparam String Contains the request body ( usually the result of a HTML FORM ).
Iter DWORD Current index while in a beginiteration construct ( 0 based )
htmlapath String From the W3SVC\Parameters\HtmlaPath::REG_SZ registry entry. This
allow the .htr files to be location independent.
arg1 String Access the 1st sub-parameter in urlparam, where sub-parameters are
separated with a ‘?’
arg2 String Access the 2nd sub-parameter in urlparam.
arg3 String Access the 3rd sub-parameter in urlparam.
Directory browsing
rootdir String Root directory of the current sub-directory browsing, with no tail ‘\’
except for the drive root directory
basedir String Root directory of the current sub-directory browsing, with no tail ‘\’
dircount DWORD Number of iteration of the direntry field
direntry String Iterated field for all sub-directories of rootdir ( except ‘.’ & ‘..’ ), without
leading or trailing ‘\’
dircompcount DWORD Number of iteration of the dircompentry & dirfcompentry fields
dircompentry String Iterated field for all components of the rootdir path, without leading or
trailing ‘\’ except for the drive root directory.
dirfcompentry String Iterated fields giving the full path for all component of the rootdir path,
without leading or trailing ‘\’ except for the drive root directory.
drivecount DWORD Number of iteration of the drivexxxentry fields.
drivenameentry String Drive name ( e.g. “c:” )
drivelabelentry String Drive label
drivetypeentry DWORD Drive type : 2 is removable, 3 is hard disk, 4 is network drive
6 Error code
The “reqstatus” variable will contain one of the following status indication :

Numeric value Description

0 No error
1000 Out of resource ( out of memory, can’t create NT object, … )
2000 Common service config ( INET_COM_CONFIG_INFO ) read error
2010 User enumeration read error
2020 User disconnection error
2100 Internet service config ( INET_INFO_CONFIG_INFO ) read error
2200 W3 config read error
2300 FTP config read error
2400 Gopher config read error
2500 Internet service config ( INET_INFO_CONFIG_INFO ) write error
2600 W3 config write error
2700 FTP config write error
2800 Gopher config write error
2900 Common service config ( INET_COM_CONFIG_INFO ) write error
4000 Reference ( cf. Discussuion of references in the verb section ) not found
5000 Invalid syntax in a verb parameter
6000 Invalid variable type
7000 Invalid variable name used by a FORM statement
8000 Invalid variable value used by a FORM statement
9000 Variable not found
10000 Too many nested If
11000 If nesting underflow ( i.e. endif without matching if )
12000 Variable setting validation failed
13000 Access Denied while browsing directories
7 Revision History
Version Author Notes Date
0.1 Phillich Initial draft January 9, 1996
0.2 Phillich Various additions January 10, 1996
0.3 Phillich Various additions, January 18, 1996
change syntax of
redirect,
disconnect user
0.4 Phillich Directory March 6, 1996
browsing, various
additions

Microsoft Confidential 1