docs: add comprehensive Routing Filters manual (PDF and Markdown)

docs/RoutingFilters.md

@@ -0,0 +1,187 @@
+# DebTik Network Appliance — Οδηγός Routing Filters & Πολιτικών Δρομολόγησης
+
+**Έκδοση Λογισμικού:** 1.3.11+  
+**Routing Engine:** BIRD 2 (v2.17+)  
+**Σύνταξη:** MikroTik RouterOS v7 Scripting Layer  
+**Αντίστοιχο PDF Αρχείο:** [`docs/RoutingFilters.pdf`](RoutingFilters.pdf)
+
+---
+
+## 1. Εισαγωγή & Αρχιτεκτονική Λειτουργίας
+
+Τα **Routing Filters** στο DebTik αποτελούν τον κεντρικό μηχανισμό επιβολής πολιτικής δρομολόγησης (Routing Policy) για τα δυναμικά πρωτόκολλα BGP και OSPF. Η υλοποίηση βασίζεται στην πανίσχυρη μηχανή δρομολόγησης **BIRD 2**, παρέχοντας ταυτόχρονα ένα συντακτικό επίπεδο απόλυτα συμβατό με το γνώριμο περιβάλλον του **MikroTik RouterOS v7**.
+
+### Βασικές Αρχές Λειτουργίας
+* **Αλυσίδες Κανόνων (Chains):** Οι κανόνες ομαδοποιούνται σε λογικές αλυσίδες (π.χ. `Internal`, `bgp-in`, `bgp-out`). Κάθε αλυσίδα μεταφράζεται στο BIRD 2 σε διαδικαστική συνάρτηση `function fn_filter_<Chain>()` και σε αυτόνομο φίλτρο `filter filter_<Chain>`.
+* **Σειριακή Εκτέλεση (Rule Order):** Οι κανόνες αξιολογούνται αυστηρά με βάση τον αριθμό σειράς (`#`, π.χ. 10, 20, 30). Ο μικρότερος αριθμός προηγείται.
+* **Τερματικές Ενέργειες (Terminal Actions):** Το `accept;` ή το `reject;` τερματίζει ακαριαία την αξιολόγηση της αλυσίδας για τη συγκεκριμένη διαδρομή.
+* **Μη-τερματική Επεξεργασία (Passthrough):** Επιτρέπει την τροποποίηση ιδιοτήτων (Local Preference, Communities, Prepending, Metric) χωρίς διακοπή της αλυσίδας, επιτρέποντας στη διαδρομή να ελεγχθεί από επόμενους κανόνες.
+* **Προεπιλεγμένη Απόρριψη (Default Deny):** Αν μια διαδρομή περάσει όλους τους κανόνες μιας αλυσίδας χωρίς να ταιριάξει σε κανέναν (unmatched), απορρίπτεται αυτόματα στο τέλος (`reject;`).
+* **Αυτόματη Προστασία Advertised Networks (v1.3.11+):** Στα εξερχόμενα φίλτρα BGP (`OutFilter`), τα ρητά δηλωμένα Advertised Networks (`OutputNetworks` / Blackhole Static) και οι επιλογές αναδιανομής (Connected/Static) προστατεύονται αυτόματα και δεν απορρίπτονται από το default reject, εκτός αν ο χρήστης ορίσει ρητό κανόνα απόρριψης.
+
+---
+
+## 2. Δομή Διεπαφής Χρήστη (Policy Filters Web UI)
+
+Η πρόσβαση γίνεται από το μενού **Routing &rarr; Policy Filters**.
+
+### Καρτέλες (Tabs)
+| Καρτέλα | RouterOS Path | Περιγραφή & Λειτουργία στο BIRD 2 |
+| :--- | :--- | :--- |
+| **Rules** | `/routing filter rule` | Εκτελέσιμοι κανόνες φιλτραρίσματος. Ορίζουν κριτήρια ελέγχου και ενέργειες (Accept/Reject/Set). |
+| **Community Lists** | `/routing filter community-list` | Ονομαστικές λίστες BGP Communities (π.χ. `65000:100`). Μεταφράζονται σε `define comm_<Name> = [...]`. |
+| **AS Lists** | `/routing filter num-list` | Ονομαστικές λίστες αυτόνομων συστημάτων (ASNs / Ranges). Μεταφράζονται σε `define aslist_<Name> = [...]`. |
+
+### Εργαλεία Toolbar
+* **+ New:** Άνοιγμα παραθύρου δημιουργίας νέου στοιχείου ανάλογα με την ενεργή καρτέλα.
+* **Enable / Disable:** Άμεση ενεργοποίηση ή απενεργοποίηση της επιλεγμένης γραμμής (Σημαία `A` για Active, `X` για Disabled).
+* **Remove:** Οριστική διαγραφή του επιλεγμένου κανόνα ή λίστας.
+* **Chain Filter Dropdown:** Επιλογή συγκεκριμένης αλυσίδας για εστιασμένη προβολή.
+* **Find... (Ζωντανή Αναζήτηση):** Άμεσο φιλτράρισμα γραμμών με αναζήτηση κειμένου, IP, CIDR, ή σχολίου.
+* **Κουμπιά ▲/▼ (Αναδιάταξη):** Αλλάζουν τη σειρά εκτέλεσης (`Rule Order`) μετακινώντας τον κανόνα πάνω ή κάτω.
+
+---
+
+## 3. Πλήρης Οδηγός Σύνταξης Σεναρίων (Script Syntax Reference)
+
+### 3.1 Συνθήκες Ελέγχου (Match Conditions)
+| Σύνταξη RouterOS v7 | Σύνταξη BIRD 2 | Λειτουργία & Παράδειγμα |
+| :--- | :--- | :--- |
+| `dst in A.B.C.D/M` | `net ~ [ A.B.C.D/M+ ]` | Έλεγχος αν το prefix περιέχεται στο subnet (π.χ. `dst in 10.0.0.0/8`). |
+| `dst in A.B.C.D/M{L,H}` | `net ~ [ A.B.C.D/M{L,H} ]` | Έλεγχος subnet με εύρος μάσκας (π.χ. `dst in 192.168.0.0/16{24,28}`). |
+| `dst == A.B.C.D/M` ή `dst = A.B.C.D/M` | `net = A.B.C.D/M` | Ακριβής ταύτιση προθέματος (π.χ. `dst == 0.0.0.0/0`). |
+| `dst != A.B.C.D/M` | `net != A.B.C.D/M` | Αποκλεισμός συγκεκριμένης διαδρομής. |
+| `dst-len == N` / `net.len = N` | `net.len = N` | Ακριβές μήκος μάσκας. |
+| `dst-len <= N` / `>= N` | `net.len <= N` / `>= N` | Εύρος μήκους μάσκας (π.χ. `net.len <= 24`). |
+| `protocol <name>` | `source = RTS_<NAME>` | Έλεγχος πρωτοκόλλου: `bgp`, `ospf`, `connected`, `static`. |
+| `bgp-communities includes A:B` | `(A, B) ~ bgp_community` | Έλεγχος αν περιέχεται συγκεκριμένο community. |
+| `bgp-communities in ListName` | `bgp_community ~ comm_ListName` | Έλεγχος αν το community ανήκει στην Community List. |
+| `bgp-as-path in ListName` | `bgp_path.last ~ aslist_ListName` | Έλεγχος αν το γειτονικό AS ανήκει στην AS List. |
+| `bgp-as-path "pattern"` | `bgp_path ~ [= * pattern * =]` | Αντιστοίχιση διαδρομής AS με regular expressions (π.χ. `"^65000_"`). |
+| `&&`, `\|\|`, `!` | `&&`, `\|\|`, `!` | Λογικοί τελεστές: AND, OR, NOT. |
+
+### 3.2 Ενέργειες & Τροποποίηση Ιδιοτήτων (Actions & Set Attributes)
+| Ενέργεια RouterOS v7 | Σύνταξη BIRD 2 | Περιγραφή & Επίπτωση |
+| :--- | :--- | :--- |
+| `accept;` | `accept;` | **Τερματική αποδοχή.** Το route γίνεται δεκτό και σταματά η αξιολόγηση. |
+| `reject;` / `discard;` | `reject;` | **Τερματική απόρριψη.** Το route κόβεται αμέσως. |
+| `passthrough;` | *(non-terminal)* | **Μη-τερματική ενέργεια.** Εκτελεί τα `set` και συνεχίζει στον επόμενο κανόνα. |
+| `set bgp-local-pref <N>;` | `bgp_local_pref = <N>;` | BGP Local Preference (default 100). Υψηλότερη τιμή = προτιμητέα έξοδος. |
+| `set bgp-med <N>;` | `bgp_med = <N>;` | Multi-Exit Discriminator. Χαμηλότερη τιμή = υπόδειξη εισόδου προς γείτονα. |
+| `set bgp-path-prepend <N>;` | `bgp_path.prepend(...);` | Προσθήκη 1-10 φορές του τοπικού AS στο AS Path (Backup uplink). |
+| `set bgp-communities.add <A:B>;` | `bgp_community.add((A,B));` | Προσθήκη Community στη διαδρομή. |
+| `set bgp-communities.delete <A:B>;`| `bgp_community.delete((A,B));` | Αφαίρεση Community από τη διαδρομή. |
+| `set distance <N>;` | `preference = <N>;` | Administrative Distance / Preference στον τοπικό πίνακα. |
+| `set gw <IP>;` | `gw = <IP>;` | Εξαναγκαστική αλλαγή Next-Hop IP gateway. |
+
+---
+
+## 4. BGP Community Lists & AS Lists
+
+### 4.1 Community Lists
+```bird
+# Ορισμός στο /etc/bird/bird.conf:
+define comm_AWMN_COMM = [ (65000, 100), (6610, 200) ];
+
+# Χρήση σε κανόνα φίλτρου:
+if (bgp_community ~ comm_AWMN_COMM) then {
+    bgp_local_pref = 150;
+    accept;
+}
+```
+
+### 4.2 AS Lists
+```bird
+# Ορισμός στο /etc/bird/bird.conf:
+define aslist_TIER1_ISPS = [ 65000..65010, 6610, 17244, 3356 ];
+
+# Χρήση σε κανόνα φίλτρου:
+if (bgp_path.last ~ aslist_TIER1_ISPS) then {
+    bgp_local_pref = 200;
+    accept;
+}
+```
+
+---
+
+## 5. Σύνδεση με BGP Peering (InFilter, OutFilter & Export Policy)
+
+### In-Filter (Εισερχόμενη Πολιτική)
+* Εφαρμόζεται στα εισερχόμενα routes από το peer.
+* Διαδρομές που εκτελούν `accept;` εγκαθίστανται στον πίνακα `master4`.
+* Unmatched διαδρομές απορρίπτονται (`reject;`).
+
+### Out-Filter (Εξερχόμενη Πολιτική - v1.3.11+ Αρχιτεκτονική 3 Επιπέδων)
+1. **Επίπεδο 1 — Κανόνες Χρήστη:** Εκτελείται η συνάρτηση `fn_filter_<Chain>()`. Ρητό `reject;` ή `accept;` εφαρμόζεται άμεσα.
+2. **Επίπεδο 2 — Advertised Networks:** Διαδρομές που δηλώθηκαν στα `OutputNetworks` ή `BGPNetworks` γίνονται αυτόματα `accept`.
+3. **Επίπεδο 3 — Redistribution:** Αν είναι ενεργό το `Redistribute Connected` ή `Redistribute Static`, εξάγονται αυτόματα.
+4. **Default Deny:** Οτιδήποτε άλλο απορρίπτεται (`reject;`).
+
+```bird
+# Παράδειγμα παραγόμενου κώδικα BIRD 2:
+protocol bgp bgp_bgp_peer_1 {
+    ipv4 {
+        import filter filter_Internal;
+        export filter {
+            fn_filter_Internal();
+            if proto = "bgp_nets_bgp_bgp_peer_1" then accept;
+            if proto = "bgp_static_nets" then accept;
+            if source = RTS_DEVICE then accept;
+            if source ~ [ RTS_STATIC, RTS_INHERIT ] then accept;
+            reject;
+        };
+    };
+}
+```
+
+---
+
+## 6. Πρακτικές Συνταγές (Recipes)
+
+### Συνταγή 1: eBGP Inbound ISP Filter
+```routeros
+# Chain: isp-in
+if (dst == 0.0.0.0/0) { accept; }
+if (dst in 10.0.0.0/8 || dst in 172.16.0.0/12 || dst in 192.168.0.0/16 || dst in 127.0.0.0/8) { reject; }
+if (net.len > 24) { reject; }
+if (true) { set bgp-local-pref 100; accept; }
+```
+
+### Συνταγή 2: Active / Backup Uplink με AS Prepending
+```routeros
+# ISP-A Inbound (isp-a-in):
+if (true) { set bgp-local-pref 200; accept; }
+
+# ISP-B Inbound (isp-b-in):
+if (true) { set bgp-local-pref 100; accept; }
+
+# ISP-B Outbound (isp-b-out):
+if (dst in 192.168.130.0/24 || dst in 192.168.131.0/24) {
+    set bgp-path-prepend 2;
+    accept;
+}
+```
+
+### Συνταγή 3: Χρήση Passthrough
+```routeros
+# Chain: customer-out | Rule 10
+if (dst in 100.64.0.0/16) {
+    set bgp-communities.add 65000:500;
+    passthrough;
+}
+# Rule 20
+if (dst in 100.64.64.0/24) { accept; }
+```
+
+---
+
+## 7. Διαγνωστικά BIRD CLI (birdc)
+
+| Εντολή CLI | Περιγραφή & Χρησιμότητα |
+| :--- | :--- |
+| `birdc show protocols` | Κατάσταση όλων των πρωτοκόλλων (BGP, OSPF, Static) και uptime. |
+| `birdc show protocols all <peer>` | Στατιστικά φίλτρων: *Import updates, rejected, filtered, accepted* & *Export updates*. |
+| `birdc show route export <peer>` | Εμφανίζει ποιες διαδρομές ανακοινώνονται αυτή τη στιγμή προς το peer. |
+| `birdc show route import <peer>` | Εμφανίζει τις διαδρομές που εισήχθησαν από το peer. |
+| `birdc show route filtered <peer>` | Εμφανίζει διαδρομές που απορρίφθηκαν από την πολιτική. |
+| `birdc restart <peer>` | Επανεκκινεί άμεσα το session για στιγμιαία επαναξιολόγηση των φίλτρων. |