STREAM::match

Description

Returns the characters most recently matched by the Stream Profile.
Available in the STREAM_MATCHED event,
STREAM::match
lets you log matches or test them in ways which are hard for regular expressions (such as arithmetic comparisons). You may use STREAM::replace to control whether and how a given match is replaced in the data stream.

Syntax

STREAM::match

STREAM::match

  • Returns the string of characters most recently matched by the Stream Profile expression.

This command returns a string of Unicode characters (not binary octets) which were obtained by translating the actual data stream octets according to the current STREAM::encoding mode.
By default, data stream octets with (binary) values from 0x80 to 0xFF are represented by Unicode characters in the range
\u0080–\u00ff

. However, when

STREAM::encoding utf-8

has been invoked

STREAM::match
may return fewer Unicode characters than the number of data-stream binary octets that were matched (because UTF-8 may use several octets to encode a single character).
When you use
STREAM::encoding ascii

(the default), you may invoke

[binary format a* [STREAM::match]]
to recover the original data octets into a TCL binary string.

Examples

Log each string matched by the Stream Profile (as configured or as requested by an iRule using STREAM::expression).
when STREAM_MATCHED {
   # log each match found by the stream profile
   log local0.info "Stream filter matched: [STREAM::match]"
}

Change the http:// in all response URL’s of the form http://example.com to https:// (ask client to use TLS).
when HTTP_REQUEST {
  # disable the stream filter for generic requests
  STREAM::disable
}

when HTTP_RESPONSE {
  # Disable the stream filter by default
  STREAM::disable

  # Check if response type is text
  if {[HTTP::header value Content-Type] starts_with "text"} {
    # Match all instances of http://example.com or http://xxx.example.com (and
    # don't supply any replacement, but we will override that later)
    STREAM::expression {=http://([^.]*[.])*example.com==}

    # Enable the stream filter just for this response
    STREAM::enable
  }
}

when STREAM_MATCHED {
  # get the URL-portion that was matched and change the protocol to https
  set tmp [string map [list "http://" "https://"] [STREAM::match]]

  # tell the stream profile to replace the matched data with the modified value
  STREAM::replace $tmp

  # log the change
  log local0.info "[IP::client_addr]_[TCP::local_port]: matched [STREAM::match], replaced with: ${tmp}"
}

Log output:
Rule stream_expression_rule : 10.0.0.1_3413: matched http://test.example.com, replaced with https://test.example.com
Rule stream_expression_rule : 10.0.0.1_3413: matched http://example.com, replaced with https://example.com

Events