FILTERING

Description of the language used for filter expressions.

Author: Shane Alcock <salcock@waikato.ac.nz>, Ken Keys

----------------------------------------------------


The language itself has a relatively simple structure.  A filter expression is
a series of clauses, separated by the word 'and'.  A clause consists of two
parts: a term which describes the feature to filter on, and a list of one or
more values to match.  Values may be surrounded by double quotes if they
contain spaces or could be mistaken for a keyword.

If a filter expression contains multiple clauses (separated by "and"), a match
will only occur if there is a successful match on *all* of the clauses.

The accepted terms and their meaning are listed below.  Most terms take one or
more values, indicated by a trailing "..." in the listing; each of these terms
can be specified only once in the filter, and it will be considered a match if
any one of the provided values matches (you can think of the values as being
joined by an implicit 'or').  Terms listed without "..." accept only one
value, but can be specified multiple times in the filter expression.

  project <name>...   (abbreviation: proj)
      restrict the stream to only records from a specific project      

  collector <name>...   (abbreviation: coll)
      restrict the stream to only records from a specific collector

  type {ribs|updates}...
      restrict the stream to only records of a certain type, e.g. updates.

  elemtype {ribs|announcements|withdrawals|peerstates}...
      restrict the stream to only elements of the given type.

  peer <asn>...
      restrict the stream to only those elements from a particular peer ASN

  prefix {[<specificity>] <prefix>}...
      restrict the stream to only elements with an IP prefix that matches
      the given <prefix>.  The optional <specificity> determines the
      type of match required:
        exact:  exact match
        more:   exact match or more specific
        less:   exact match or less specific
        any:    exact match or more or less specific
      Any number of <specificity> and <prefix> values may be listed;
      each <prefix> uses the most recent <specificity> listed, or "more"
      if none has been listed yet.

  ipversion {4|6}...   (abbreviation: ipv)
      restrict the stream to only elements with prefixes belonging to
      the given IP address version.

  community <asn>:<value>...   (abbreviation: comm)
      restrict the stream to only elements that have a community that
      matches the given community string.  Either of <asn> <value> may be
      "*" to match anything, e.g. '*:300' will match all elements with
      a community value of 300, regardless of the ASN.

  aspath <regex>   (abbreviation: path)
      restrict the stream to only elements with an AS Path that matches
      the provided Cisco regular expression.  In a Cisco regular
      expression, characters in "|()[].^$*+?\" have the same meaning as
      in POSIX extended regular expressions; characters in "{}" have no
      special meaning; and the character "_" matches beginning of string,
      end of string, space, braces, comma, or underscore, i.e. the same as
      "(^|$|[ {},_])".  POSIX backreferences are also supported.

      For example, the expression '^681_1444_' will match any AS Paths
      that begin with AS681 followed by AS1444.

      Placing a '!' in front of the regular expression will cause the
      result to be negated, i.e. the element will only be streamed
      if the path does NOT match the regular expression. For example,
      "!^681_" will stream all paths that do not begin with AS681.

Examples
========

Filter only updates from the rrc00 collector:
  'collector rrc00 and type updates'

Filter the prefix '1.2.3.0/22' or any more specific prefixes from either
the rrc06 or the route-views.jinx collectors:
  'prefix more 1.2.3.0/22 and collector rrc06 route-views.jinx'

Filter IPv6 records that have a peer asn of 25152 and include the ASN
4554 in the AS path:
  'ipversion 6 and peer 25152 and path "_4554_"'