(hopefully) better explaination of white lists...

... and how they interact with tag_as_set and
[prefix|origin]_not_present_in_as_set communities.

closes #18

config.d/clients.yml

@@ -148,13 +148,15 @@ clients:
           # "escape" IRRdb-based filters and to be always accepted.
           # Entries of this list are made up by prefixes and an
           # optional ASN which, if present, is matched against the
-          # origin ASN. In this case, routes that pass the IRRdb
-          # filters are tagged with 'prefix_not_present_in_as_set'
-          # and 'origin_not_present_in_as_set' accordingly to the
-          # configured policy.
+          # origin ASN. In this case, if the general 'filtering.
+          # irrdb.tag_as_set' option is set, routes that pass the
+          # IRRdb filters because included in this white list are
+          # tagged with 'prefix_not_present_in_as_set' and
+          # 'origin_not_present_in_as_set' communities.
           #
           # The last two, 'white_list_pref' and 'white_list_asn'
-          # are more "tricky". They allow to treat prefixes and ASNs
+          # are more "tricky" and it is likely that they don't need
+          # to be used at all. They allow to treat prefixes and ASNs
           # as if they were part of the client's AS-SET.
           # This implies that filters and features based on IRRdb
           # data are also applied as if routes were validated against

config.d/general.yml

@@ -200,7 +200,8 @@ cfg:
 
       # Tag routes whose prefix is (not) present in a client's AS-SET.
       # If a client's 'enforce_[origin|prefix]in_as_set' is True
-      # then unauthorized prefixes are rejected and not tagged.
+      # then unauthorized routes are rejected and not tagged
+      # (unless they match a client-level 'white_list_route' entry).
       # BGP communities used to tag these routes are
       # '[origin|prefix]_(not_)present_in_as_set'.
       #

docs/CONFIG.rst

@@ -173,6 +173,8 @@ White lists
 
 In addition to prefixes and ASNs gathered as said above, white lists can be configured at client level to manually enter prefixes and origin ASNs that will be treated as if they were included within clients' AS-SET.
 
+If the ``filtering.irrdb.tag_as_set`` general option is also set to True, routes that fail the basic IRR filters but that are accepted solely because they match a white list entry are tagged with the ``prefix_not_present_in_as_set`` and ``origin_not_present_in_as_set`` informational communities.
+
 Example:
 
 .. code:: yaml

docs/GENERAL.rst

@@ -396,7 +396,8 @@ https://arouteserver.readthedocs.io/en/latest/CONFIG.html
 - ``tag_as_set``:
   Tag routes whose prefix is (not) present in a client's AS-SET.
   If a client's **enforce_[origin|prefix]in_as_set** is True
-  then unauthorized prefixes are rejected and not tagged.
+  then unauthorized routes are rejected and not tagged
+  (unless they match a client-level **white_list_route** entry).
   BGP communities used to tag these routes are
   **[origin|prefix]_(not_)present_in_as_set**.
 

tests/live_tests/scenarios/tag_as_set/README.rst

@@ -92,7 +92,7 @@ AS4 announces:
         4.3.1.0/24      4 41            no              yes (WL)        64513 64514        the same
         4.0.3.0/24      4 41            yes             yes (WL)        64512 64514        64513 64514
         4.4.0.0/16      4 44            r WL            r WL            64513 64515        the same
-        4.4.1.0/24      4 44            r WL            r WL            rejected           rejected
+        4.4.1.0/24      4 44            r WL KO         r WL            rejected           rejected
         4.5.1.0/24      4 43            r WL            r WL            64513 64515        the same
         4.5.2.0/24      4 45            r WL            r WL KO         rejected           rejected
         4.6.1.0/24      4 45            r WL            r WL            64513 64515        the same