Add README

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-*'