From 078371692f68d5520f2af970c82e1fc1a4a64a1c Mon Sep 17 00:00:00 2001
From: Alexander Zubkov <green@qrator.net>
Date: Wed, 1 Dec 2021 17:00:34 +0100
Subject: [PATCH] add README

---
 README | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 README

diff --git a/README b/README
new file mode 100644
index 0000000..d2a2e6d
--- /dev/null
+++ b/README
@@ -0,0 +1,95 @@
+
+# plag
+
+Tools to optimize a list of IP (v4 or v6) prefixes.
+The tools read prefix list on stdin and output the result to stdout.
+
+ - plagmax - returns a minimal superset of prefixes (loose mode)
+ - plageq - aggregates to equal set of prefixes with submasks
+
+## plagmax
+
+`plagmax` aggregates prefixes in loose mode, in case where all subprefixes
+are also allowed.
+So in the output all subprefixes are ignored and neighbour prefixes are folded.
+
+### Example
+
+Input:
+
+```
+10.0.0.0/24
+10.0.1.0/24
+10.0.2.0/24
+10.0.2.1/32
+10.0.3.0/24
+```
+
+Output:
+
+```
+10.0.0.0/22
+```
+
+## plageq
+
+`plagmax` aggregates prefixes in strict mode.
+So it does not add or remove prefixes, but aggregates sets of subprefixes
+with the same mask into larger prefixes with a submask.
+It tries to get the minimal number of prefixes in its output.
+
+### Example
+
+Input:
+
+```
+10.0.0.0/24
+10.0.1.0/24
+10.0.2.0/24
+10.0.2.1/32
+10.0.3.0/24
+```
+
+Output:
+
+```
+10.0.0.0/22{24,24}
+10.0.2.1/32
+```
+
+## Building
+
+You will need only a C compiler and a standard library to build the tools.
+A simple `make` run should do the job.
+
+```bash
+$ make
+gcc -O3 -o lib.o -c lib.c
+gcc -O3 -o plagmax plagmax.c lib.o
+gcc -O3 -o plageq plageq.c lib.o
+```
+
+## Running
+
+The tools read stdin where they expect IP prefixes one per line.
+Prefixes are of the standard form: `<IP>[/<mask>]`.
+Both IPv4 and IPv6 are allowed, you can freely mix them
+and the input doesn't need to be sorted.
+Mask part is optional, in this case prefix is considered a single IP
+and the default of `32` for IPv4 and `128` for IPv6 is used.
+
+`plagmax` outputs simple prefixes in the same format and
+`plageq` outputs prefixes with added submask range:  
+`<IP>/<mask>{<low>,<high>}`  
+This matches all prefixes, having masks in range `<low>`-`<high>`
+(inclusive) that lie inside the prefix `<IP>/<mask>`.
+In case `<mask> = <low> = <high>` the submasks part is omitted.
+This notation of submasks is used in `bird` routing daemon.
+
+You can use `bgpq4` tool for example to fetch the list of prefixes
+and pipe its output to the tools:
+
+```bash
+bgpq4 -4 -F '%n/%l\n' as-set-name | ./plageq > as-set-name.ipv4.strict.txt
+bgpq4 -6 -F '%n/%l\n' as-set-name | ./plagmax > as-set-name.ipv6.loose.txt
+```