From 8171f16f1811f28dc3cb0299e0ac8f3ad277b1b6 Mon Sep 17 00:00:00 2001
From: Timotej Lazar <timotej.lazar@fri.uni-lj.si>
Date: Thu, 20 Jul 2023 13:26:36 +0200
Subject: [PATCH] Add README

---
 README.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..73d85fa
--- /dev/null
+++ b/README.md
@@ -0,0 +1,29 @@
+These Ansible roles set up servers running various Linux distributions to participate in BGP routing. Device and IP address data are pulled from NetBox. A separate VRF `mgmt` is configured for a L2 management interface.
+
+# Setup
+
+Each server should have the following information recorded in NetBox:
+
+  - network interfaces `mgmt*`: used for management (Ansible) access; must define MAC and IP address
+  - network interfaces `lan*`: used for BGP routing; must define MAC address
+  - network interface `lo`: must define the IP address to announce over BGP, also serves as router ID
+
+For the management IP address, another address in the same prefix should be defined with the tag `gateway`.
+
+# Run
+
+Create a read-only token in NetBox. Define required variables:
+
+    # one for nb_inventory and one for nb_lookup
+    export NETBOX_API_KEY=<token>
+    export NETBOX_TOKEN="${NETBOX_API_KEY}"
+    # one for both
+    export NETPOX_API=<netbox API endpoint>
+
+Run one-off tasks with (add `--key-file` or other options as necessary):
+
+    ansible -i inventory.yml -m ping 'server-*'
+
+Run a playbook with:
+
+    ansible-playbook setup.yml -i inventory.yml -l 'server-*'