SREhttp/2 Selector-Specific Advanced Options

Contents:

• 1. Introduction
• 2. Specifying advanced options
• 3. The advanced options
• 3a. EXEC procedures
• 3b. HEADER and RESPONSE directives.
• 3c. Server Side Include Suppression
• 3d. Mime types
• 3e. Replacement rules
• 3f. Setting variables
• 3g. Controlling the maximum number of simultaneous users of a resource
• 3h. Modifying a realm's attributes on a client specific basis
• 4. A sample advanced options file

1) Introduction

• execution of EXEC ("mid-filter") procedures,
• customization of response headers
• suppression of specific server side includes.
• selector specific mime type
• selector specific replacement-rules
• set the EXPIRES, MD5, PRE_RESPONSE, POST_RESPONSE and other parameters
• specify the maximum number of simultaneous users of a resource
• modifying the realm's attributes on a client specific basis
• in the future, additional features may be added.

2) Specifying advanced-options

Notes:

       REALM: Myrealm
       RULE: /SAMPLES/*
       Option: header add X-Grader: this is a mediocre resource
       Option: set expires 0.1

       Realm: HerRealm
       Rule: /VIOLET/*
       Option_file: cfg/her_opts.opt

       header: add X-Confirm: 13
       ssi_no code
       set pre_response 0

3) The advanced options

1. EXEC procedures -- execute an external REXX procedure.
2. HEADER and RESPONSE directives -- specify a custom response header
3. SSI_suppression directives -- suppress specific SSI actions.
4. Set MIME type
5. Replacement rules
6. Set a few variables
7. Controlling the maximum number of simultaneous users of a resource
8. Modifying a realm's attributes on a client specific basis

3a) EXEC Procedures

As detailed in OUTLINE.HTM, request processing involves these steps:

1. The SRE2003 "pre-transaction" procedure
2. The SRE2003 "pre-request" procedure
3. The fast-filter
4. Invoking SREhttp/2...
5. SREhttp/2 EXEC procedures
6. SREhttp/2 "pre-response" procedure
7. SRE2003 "IM" procedures
8. The SREhttp/2 "post-response" procedure

Syntax:
    EXEC filename opt_string
where:

The EXEC procedure will be sent a set of variables:

An EXEC procedure can return either:

1. if the EXEC procedure sends a response directly to the client using SRE_COMMAND, then the EXEC procedure must return the status code returned by SRE_COMMAND (i.e.; rcode=sre_command('FILE .....'); return rcode ).

2. Otherwise, EXEC procedures should return nothing (i.e.; return ' ').
   

Notes:

• If the "filename" starts with a ! (as in the !MY_EXEC example), the name (minus the starting !) is assumed to be that of a procedure that has been loaded using the LOAD_EXEC option in the PRELOADS.CFG file. If no such procedure name has been loaded, a 500 error occurs.
• If not fully qualfied, filename is assumed to be relative to the SREHTTP2\PROCS directory.
• EXEC_SMP.REX (in the SREHTTP2\PROCS directory) contains a simple example of such an external procedure.
• MAX_USER.REX (in the SREHTTP2\PROCS directory) is an EXEC procedure used to control the maximum number of simultaneous users of a resource; where a resource is a single selector, or a set of selectors.
• Hint: one use of EXEC is to support HTTP M-extensions, as described in the HTTP Extensions RFC. Otherwise, these M-extensions will result in a 510 error return.

3b) HEADER and RESPONSE directives.

This response header customization is only available for GET and HEAD requests that invoke a file transfer (including HTML documents with server side includes).

That is, for "server side processing" requests (such as CGI-BIN scripts, SREhttp/2 addons, PUT and DELETE requests, and imagemaps) HEADER and RESPONSE entries will not be used.

  response HTTP/1.1 406 Variant not available
  header X-Webmaster-Name: Daniel Platypus
  header drop expires
  header X-comment:  X- headers are created by SREhttp/2
  header X-Our-server: $servername
  header X-Size-1: this is $size size
  header X-Code-1: this is $code code

Notes:

• Headers specified using advanced options override automatically generated headers. For example, if a cache-control header is specified as an advanced option, then the automatically generated cache-control header will not be used.
• The HEADER DROP will drop a header (if one exists). This is cumulative, so that...
     HEADER DROP X-EXPIRES
     HEADER ADD X-Expires: not-now
  yields an
      X-Expires: not-now
  response header.
• See the description of SRE_COMMAND for details on HEADER and RESPONSE SRE2003 directives.
• Note that the HEADER selector-specific option refers to response headers. In contrast, the HEADER SSI_VAR variable refers to text inserted into the top of an HTML document.

3c) Server Side Include Suppression

Syntax:
    SSI_NO opt1 ... optn
The available OPTn options are:

Examples:

   ssi_no cache
   ssi_no header    footer
   ssi_no select   #echo   #exec

3d) Mime types

You should have, at most, one MIME line per selector (latter entries are ignored).

3e) Replacement rules

The syntax is:
   REPLACE old_string==new_string

Notes:

Notes:

• If any selector-specific replacement rules are defined, then the generic (host-specfic) replacement rules are ignored (for requests that match selectors for which replacement rules are defined).

• Hint: Using Replacement rules and Load Balancing.

  Replace rules can come in handy when you are load balancing to subsidiary- sites. In order to guarantee that all requests pass through a main-site, you may have to include a <BASE href="main.site.url"> element in the <HEAD> section of HTML documents on subsidiary-sites. Since adding these elements may be tedious, the following REPLACE can be used instead:

  REPLACE </HEAD>==<BASE href="http://main.site.url"> </HEAD>

  where main.site.url should be the IP address of the main-site.

3f) Setting variables

These are:

The syntax to use is:
    SET varname value

Some examples:

   SET ENABLE_CGI_PIECES 0

   SET ETAG SIMPLE
   SET ETAG AUTO2
   SET ETAG "eT9fdty"

   SET EXPIRES  0      (do not add an offset)
   SET EXPIRES 0.66     (add a 0.66 day offset)

   SET LIMITtimeTOTAL 150  (allow 150 seconds to complete response)
   SET LIMITtimeINACTIVE 50  (allow 50 seconds of inactive time)

   SET PRE_RESPONSE 0  
   SET PRE_RESPONSE  ENCRYPT SRE_A 
   SET PRE_RESPONSE  DEFAULT 

   SET POST_RESPONSE  Class=Red Cars

   SET PUT_OVERWRITE 1
   
   SET IM 0        (0 means disable)
   SET IM DELTA   

   SET MD5 0         (suppress generation of Content-MD5 header)
   SET MD5 1         (add a Content-MD5 header)


   SET NOTIFY_MESSAGE Or, you can try <a href="altpage.htm">an alternative</a>

   SET DYNPRIV_DURATION 35

3g) Controlling the maximum number of simultaneous users of a resource

Basically, if more then this number of requests for this resource are currently active, the server will respond with a Server busy, try again in a few minutes. This can be a useful means of limiting access to CPU intensive scripts and addons.

Syntax:

4 arguments (seperated by a comma) can be included in the Option: EXEC MAX_USER.REX line in your possibly host-specific ATTRIBS.CFG file.

• family is case insensitive. If it is not specified, then the action (the portion of the selector before the ?) is used as the family.
• If max_users is not specified, then a value of 1 is used.
• if maxuser_failure_file is not specified (it should be relative to your possibly host-specific CFG directory), a simple "server is busy" response is returned.
• If retryafter is not specified, a Retry-After response header will NOT be added.
• Note that family, whether it is explicitly defined or not, is not host specific. That is, the set of users of a family of resources (noting that a family can consist of just one resource) is not sub-divided into what host the client sent a request to.

Examples (of entries in ATTRIBS.CFG)

   Option: EXEC max_users.rex
   Option: EXEC max_users.rex family1
   Option: EXEC max_users.rex familyN, 6, FailFamn.htm , 30
   Option: EXEC !max_u   familyN ,4  

Notes

• You can use the Limit the number of simultaneous users of a resource tool to set these limits.

• As the last example suggests ...

  if you intend to use MAX_USER.REX frequently, you might want to use the LOAD_EXEC option (in PRELOADS.CFG) to "load" this code into macrospace.

• As with the LOGON_FAIL_FILE, when the MAXUSER_FAIL_FILE is an HTML document, server side includes are not attempted. However, a few special substitutions will occur (when the MAXUSER_FAIL_FILE is an HTML document):

  <!--#URL-->	phrases are substituted with the request selector.
  <!--#SERVER-->	phrases are substituted with the servername.
  <!-- #MESSAGE -->	phrases are substituted with a short description of the reason for failure
  <!-- #LINK -->	phrases are substituted with a URL which points back to this resource

• The retryafter argument only works with HTTP/1.1 browsers. As an alternative, that works with almost all currently used browsers, you can include the following in the <HEAD> section of an HTML failure file:
      <META HTTP-EQUIV="Refresh" CONTENT="6">
  where the 6 is the number of seconds the browser will wait before trying again -- of course, you can change this 6 to some other integer value.
• To repeat: the family, whether it is explicitly defined or not, is not intrinsically host or selector specific (though, you can achieve this specificity by only using a particular family in one host-specific realm).
  Note that the max_users is selector specific. This means that even though several resources may belong to a family, not all are equally constrained (requests for some selectors will be honored even if the family is being heavily used, while others will not).

3h) Modifying a realm's attributes on a client specific basis

For example, assume two sets of users; one with the NL client privilege and the other with the AL client privileges. Then, you could modify the redirect attribute as a function of these privileges. For example, for /champs.htm, redirect the NL clients to /giants.html and the AL clients to /angels.htm.

Syntax:

Client c_file

where:

c_file is a filename. If a relative file name, it will be relative to the host-specific CFG subdirectory.

In addition to a Privs: attribute, you can specify permissions, redirect, and advanced options.

You can not specify rule, host, requires, failure, or option_file.

;this is used to modify attributes on a client specific basis
; it is used with the SPORTS_VU realm, which is defined with the rule /SPORTS/WATCH.HTM

privs: soccer
redirect: perm=http://www.mls.com

privs: baseball 
redirect: perm=http://www.mlb.com

privs: football
redirect: perm=http://www.nfl.com

; amateur we handle here
privs: amateur
permissions: no_log no_ssi

;otherwise, use the attributes defined in the SPORTS_VU realm

4) A sample "advanced options file"

;------------- Begin Example ------------
; call the sample external procedure
exec exec_smp.rex This is an argument , with commas embedded.
;
; add a custom response header
header add X-Webmaster-Name: Timothy Platypus
;
; Suppress headers, footers, and server side "excludes"
ssi_no header footer 
ssi_no select

; replace some strings in SSI html files
replace C.== $ Customiz 

; suppress content-md5 header
set md5 0

;------------- End Example ------------