filterName="filterSpec" CMAP="filterSpec":filterName:connMap filterName == FCL | FTOCL | FFROMCL | FSV | FTOSV | FFROMSV | FMD | FTOMD | FFROMMD filterSpec == filterCommand | CFIscriptName | tcprelay://host:portfilterName is named as FXX, FTOXX and FFROMXX where XX is one of CL (client), SV (server) and MD (MASTER-DeleGate). Filter commands for FXX are bidirectional filter given file descriptor 0 bound for the client, and file descriptor 1 bound for the DeleGate. Filters commands for FTOXX and FFROMXX getting input from standard input and put output to standard output which is bound for XX. A unidirectional filter at a remote host can be used by connecting it on TCP by "tcprelay://host:port"
A filter can be applied conditionally based on circuit level information, using CMAP parameter like follows:
For FTOXX and FFROMXX filters,
CFI script enables selecting an appropriate filter
to be applied to each data depending on the type of data.
Instead of direct usage of a filter program like
FTOCL=filter.cfi where filter.cfi is a file
in the CFI script format.
Or a CFI script can be loaded from remote host like
FTOCL=URL via HTTP or FTP.
When the file name of CFI scripts or a filter command referred
in the script is specified in relative path name,
it is searched in LIBPATH.
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" | ...
CGIENV == "REQUEST_METHOD" | "SERVER_PROTOCOL" | "SERVER_NAME"
| "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 ]*
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
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.
HTTP/1.0 200 OK ... response status line Content-Type: text/html ... header Content-Length: 20 ... header ... header/body separator body of the message ... body
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
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.
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 + MIMEbodyFor 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