.. BFR Filter Element
.. highlight:: xml
Filtering Packets
=================
This is a long line of text.
Filter
------
The Filter component creates a mechanism for "deep inspection" upstream and/or downstream packets
and allowing them to be accepted or rejected::
<Filter client="client_label" server="server_label">
<Upstream>
<Accept source="source_address" destination="destination_address" function="function" />
<Reject />
</Upstream>
<Downstream>
...same accept or reject components as upstream...
</Downstream>
</Filter>
The ``Upstream`` and ``Downstream`` components are optional and may be specified in any order, but
each my only be specified once as a child of the ``Fitler`` component.
The ``Upstream`` and ``Downstream`` components have the same ``Accept`` and ``Reject`` children with
the same semantics.
Accept and Reject
~~~~~~~~~~~~~~~~~
The ``Accept`` and ``Reject`` components have identical attributes; ``source``, ``destination``,
and ``function``. If any or all of these are provided, the coorisponding value is considered a match
when the packet value is identical. For example::
<Accept source="12" />
This filter element matches and accepts all packets whose source address is ``12``, independent of
the destination address or the function. All other packets are passed to the next filter
element.
.. note:: The filter elements are processed in the order they are specified.
An element where all attributes are not specified will function as a universal match. For example::
<Reject />
This filter will reject all packets, no further filtering will be performed.
Address Filters
~~~~~~~~~~~~~~~
The ``source`` and ``destination`` address attributes may be any one of the follow forms:
======= =========================================
String Matches
======= =========================================
``:`` Any local station
``*`` Local broadcast address
``*:`` Any remote station
``n`` Local station address ``n``
``n:`` Any remote station on network ``n``
``n:*`` Remote broadcast address on network ``n``
``*:*`` Global broadcast address
======= =========================================
The correct form of address to use will depend on the layer where the filter is applied. For example,
a remote address, remote broadcast, and global broadcast are not meanful filtering packets going to
or from a local network.
Function Filters
~~~~~~~~~~~~~~~~
The ``function`` filter attributes may be one or more of the keywords in the following tables. More than
one keyword can be specified, separated by blanks.
BACnet/IP Message Types
'''''''''''''''''''''''
BVLC-RESULT,
WRITE-BROADCAST-DISTRIBUTION-TABLE, WRITE-BDT,
READ-BROADCAST-DISTRIBUTION-TABLE, READ-BDT,
READ-BROADCAST-DISTRIBUTION-TABLE-ACK, READ-BDT-ACK,
FORWARDED-NPDU, REGISTER-FOREIGN-DEVICE, READ-FOREIGN-DEVICE-TABLE,
READ-FDT, READ-FOREIGN-DEVICE-TABLE-ACK, READ-FDT-ACK,
DELETE-FOREIGN-DEVICE-TABLE-ENTRY, DELETE-FDT-ENTRY,
DISTRIBUTE-BROADCAST-TO-NETWORK, ORIGINAL-UNICAST-NPDU, ORIGINAL-BROADCAST-NPDU
Network Layer Message Types
'''''''''''''''''''''''''''
WHO-IS-ROUTER-TO-NETWORK, WHOS-RTN, I-AM-ROUTER-TO-NETWORK, IM-RTN,
I-COULD-BE-ROUTER-TO-NETWORK, I-CLD-BE-RTN, REJECT-MESSAGE-TO-NETWORK,
REJ-MTN, ROUTER-BUSY-TO-NETWORK, RBTN, ROUTER-AVAILABLE-TO-NETWORK,
RATN, INITIALIZE-ROUTING-TABLE, IRT, INITIALIZE-ROUTING-TABLE-ACK,
IRT-ACK, ESTABLISH-CONNECTION-TO-NETWORK, ECTN,
DISCONNECT-CONNECTION-TO-NETWORK, DCTN
Application Layer Message Types
'''''''''''''''''''''''''''''''
CONFIRMED-REQUEST, UNCONFIRMED-REQUEST, SIMPLEACK, COMPLEXACK,
SEGMENTACK, ERROR, REJECT, ABORT
Application Layer Confirmed Services
''''''''''''''''''''''''''''''''''''
ACKNOWLEDGEALARM, CONFIRMEDCOVNOTIFICATION, CONFIRMEDEVENTNOTIFICATION,
GETALARMSUMMARY, GETENROLLMENTSUMMARY, SUBSCRIBECOV, ATOMICREADFILE,
ATOMICWRITEFILE, ADDLISTELEMENT, REMOVELISTELEMENT, CREATEOBJECT,
DELETEOBJECT, READPROPERTY, READPROPERTYCONDITIONAL, READPROPERTYMULTIPLE,
WRITEPROPERTY, WRITEPROPERTYMULTIPLE, DEVICECOMMUNICATIONCONTROL,
CONFIRMEDPRIVATETRANSFER, CONFIRMEDTEXTMESSAGE, REINITIALIZEDEVICE,
VTOPEN, VTCLOSE, VTDATA, AUTHENTICATE, REQUESTKEY, READRANGE,
GETEVENTINFORMATION
Application Layer Unconfirmed Services
''''''''''''''''''''''''''''''''''''''
I-AM, I-HAVE, UNCONFIRMEDCOVNOTIFICATION, UNCONFIRMEDEVENTNOTIFICATION,
UNCONFIRMEDPRIVATETRANSFER, UNCONFIRMEDTEXTMESSAGE, TIMESYNCHRONIZATION,
WHO-HAS, WHO-IS, UTCTIMESYNCHRONIZATION
Samples
-------
For these and other samples, the components are described in configuration starting from
the bottom of a stack and proceeding up. In the coorisponding diagrams, upstream traffic
goes from left to right, the downstream traffic from right to left.
VLAN Filter
~~~~~~~~~~~
This sample configuration file creates a virtual network with three nodes::
<BFR>
Create a network with three nodes:
<VLAN>
<Node address="1" server="a" />
<Node address="2" server="b" />
<Node address="3" server="c" />
</VLAN>
On the first node, bind a filter:
<Filter client="a" server="ax">
Filter upstream traffic from the node to the console, accepting
traffic from address "2" but rejecting everything else:
<Upstream>
<Accept source="2" />
<Reject />
</Upstream>
No downstream filtering.
<Downstream />
</Filter>
And then bind a console:
<Console client="ax" />
On the second node, bind a echo:
<Echo client="b" />
On the third node, bind another echo:
<Echo client="c" />
</BFR>
.. figure:: vlan_filter.svg
:align: center
*VLAN Filter*
.. http://bramp.github.io/js-sequence-diagrams/
participant A
participant Filter
participant Console
participant B
participant EchoB
participant C
participant EchoC
Note over Console: Console to the\n network
Console->Filter: 1
Filter->A: 2
A->B: 3
B->EchoB: 4
Note over EchoB: swap src/dst
EchoB->B: 5
B->A: 6
A->Filter: 7
Note over Filter: Accepted from B
Filter->Console: 8
Note over Console: print echo
A->C: 9
C->EchoC: 10
Note over EchoC: swap src/dst
EchoC->C: 11
C->A: 12
A->Filter: 13
Note over Filter: reject from C
Note over Console: no output
In this sequence, the user enters a broadcast message on the console, such as this::
* 01020304
The packet travels downstream from the console to the filter (1). There is no filtering on
downstream packets, so it continues downstream to the VLAN node (2).
Node ``A`` recognises that it is a broadcast message and that it should be distributed to
all of the other nodes in the VLAN, so it provides a copy of the message to ``B`` (3) and
another copy to ``C`` (9).
Node ``B`` sends its copy of the packet upstream to the ``Echo`` component (4) which swaps
the source and destination and sends it back downstream (5). Node ``B`` recognises that it
is a unicast message and sends it to ``A`` (6). Node ``A`` sends the packet upstream to the
filter (7).
The filter receives the upstream packet, matches it against the rules in the ``Upstream``
sub-component of its configuration. The packet is accepted, then forwarded upstream to the
console (8), which then prints the packet.
Node ``C`` receives the packet from ``A`` (9), sends it upstream to the ``Echo`` component (10)
which swaps the source and destination and sends it back downstream (11). Node ``C``
recognises that it is a unicast message and sends it to ``A`` (12).
The filter receives the upstream packet, matches it against the rules in the ``Upstream``
sub-component of its configuration. The packet is rejected.