PageViews: 4,785 hits / 46 nets
home updates download manual documents feedback search ITS more

Reference Manual of DeleGate

DeleGate reference manual version 9.9 / <A Href=/delegate/Manual.shtml?CFI id=hgen>CFI</A> script
[CTX] [ALL] CFI script

CFI script

The CFI script is a simple script to select an appropriate filter to be applied to a message data relayed on DeleGate, depending on the type of data, the server name, the type of client, and so on. A CFI script is text data which starts with a magic string "#!cfi" and contains more than one filter specifications which are separated by "--" with each other.

  CFI script   == "!#cfi" NL filterUnit [ "--" NL filterUnit ]*
  filterUnit   == filterRule [ filterRule ]*
  filterRule   == matchingRule | rewriteRule | filterSpec
  matchingRule == matchingName ":" ruleBody
  matchingName == MIMEheader | X-header | CGIENV
  MIMEheader   == "Content-Type" | "User-Agent" | ...
  X-header     == "X-Status-Ver" | "X-Status-Code"
                | "X-Request-Method" | "X-Request-Ver"| "X-Request-URL" | ...
                | "PATH_INFO" | "PATH_TRANSLATED" | "HTTP_USER_AGENT" | ...
  rewriteRule  == Action "/" MIMEheader : ruleBody
  Action       == "Output" | "Remove"
  filterSpec   == filterType ":" ruleBody
  filterType   == "Body-Filter" | "CGI" | "Header-Filter"
                | "MIME-Filter" | "Message-Filter"
  ruleBody     == string NL [ SP  string NL ]*

Input Format:
The input data to CFI script is a message of application protocol in MIME format preceded with a request or a response status line of the application protocol (HTTP, SMTP, POP, NNTP). A MIME message is composed with a header and a body separated with an empty line.

  CFIinputMessage == statusLine MIMEheader NL MIMEbody
Example: a simple HTTP response message

Matching Rule:
A matchingRule indicates matching the ruleName:ruleBody to the input header. It matches when the input message has a ruleName header with a field body matches with ruleBody. If at least one of matching rules turns to be true, then the filterUnit is adopted. If no matching rule is included in a filterUnit then the filterUnit is adopted unconditionally. Currently, only a limited set of MIME headers (in request or response message) can be used for the matching. Also, some extended headers can be used to match with information not included in the original header (ex. "X-Status-Code" which means status code in response message). Matching with CGI environment variables.

Example: a matching rule

Rewriting Rule:
A rewriteRule with a prefix "Action/" to a ruleName:ruleBody specifies some simple rewriting using ruleBody data for relevant ruleName field. "Output/ruleName:ruleBody" indicates appending (or replacing) a ruleName:ruleBody field into the header. "Remove/ruleName:ruleBody" indicates removing header fields with name ruleName and body matches to ruleBody.

Filter Specification:
A filterSpec specifies a filter to be applied to the input data. The whole or a part of input message will be passed to the standard input of the filter program, then the output from the standard output of it will be forwarded to the destination (client or server) instead of the original input message.

  Body-Filter:    filter for MIMEbody
  CGI:            filter for MIMEbody
  Header-Filter:  filter for MIMEheader
  MIME-Filter:    filter for MIMEheader + MIMEbody
  Message-Filter: filter for statusLine + MIMEheader + MIMEbody
For filters of any type, the set of CGI environment variables is passed. In addition, CFI origin environments variables are passed including "SERVER_HOST" (the name of the destination server), "REQUEST_URL" (the URL of the request).

For filters of "Body-Filter" or "CGI", the "Content-Length" header in the forwarded message will be adjusted to indicate the size of the body part after the filtering. The output of "CGI" filter must preceded with the status header of CGI output.

For filters of "Header-Filter", the header part of a message will be passed to and from the filter. The start-line in the HTTP message (Request-Line or Status-Line) will be passed as a header field prefixed with "Request-Line:" or "Status-Line:".

For filters of "MIME-Filter", the whole of the MIME message consists of a header and a body is passed to and from the filter.

For filters of "Message-Filter", the whole message of the application protocol is passed to and from the filter where each message consists of a MIME message prefixed with a line representing request or response status in the application protocol.

Example: rewriting HTTP response messages

Example: dump available headers and environment variables