Public Release

examples/quickstart-vagrant/README.md

@@ -0,0 +1,154 @@
+# Quickstart Guide
+
+This guide is intended to bring up a vagrant environment with 1 lighthouse and 2 generic hosts running nebula.
+
+## Pre-requisites
+
+There are two pre-requisites prior to bringing up the vagrant environment
+
+  - build the binaries locally for the vagrant deploy
+  - create a virtualenv for ansible
+
+### Building the binaries
+
+Build the `nebula` and `nebula-cert` binaries for vagrant by doing the following
+
+`make bin-vagrant` (under the src directory with Makefile)
+
+For convenience, ansible will run this for you in every deploy (see `ansible/playbook.yml`)
+
+### Creating the virtualenv
+
+Within the `quickstart/` directory, do the following
+
+```
+# make a virtual environment
+virtualenv venv
+
+# get into the virtualenv
+source venv/bin/activate
+
+# install ansible
+pip install -r requirements.yml
+```
+
+## Bringing up the vagrant environment
+
+A plugin that is used for the Vagrant environment is `vagrant-hostmanager`
+
+To install, run
+
+```
+vagrant plugin install vagrant-hostmanager
+```
+
+All hosts within the Vagrantfile are brought up with
+
+`vagrant up` 
+
+Once the boxes are up, go into the `ansible/` directory and deploy the playbook by running
+
+`ansible-playbook playbook.yml -i inventory -u vagrant`
+
+## Testing within the vagrant env
+
+Once the ansible run is done, hop onto a vagrant box 
+
+`vagrant ssh generic1.vagrant`
+
+or specifically
+
+`ssh vagrant@<ip-address-in-vagrant-file` (password for the vagrant user on the boxes is `vagrant`)
+
+Some quick tests once the vagrant boxes are up are to ping from `generic1.vagrant` to `generic2.vagrant` using 
+their respective nebula ip address. 
+
+```
+vagrant@generic1:~$ ping 10.168.91.220
+PING 10.168.91.220 (10.168.91.220) 56(84) bytes of data.
+64 bytes from 10.168.91.220: icmp_seq=1 ttl=64 time=241 ms
+64 bytes from 10.168.91.220: icmp_seq=2 ttl=64 time=0.704 ms
+```
+
+You can further verify that the allowed nebula firewall rules work by ssh'ing from 1 generic box to the other.
+
+`ssh vagrant@<nebula-ip-address>`  (password for the vagrant user on the boxes is `vagrant`)
+
+See `/etc/nebula/config.yml` on a box for firewall rules.
+
+To see full handshakes and hostmaps, change the logging config of `/etc/nebula/config.yml` on the vagrant boxes from 
+info to debug.
+
+You can watch nebula logs by running
+
+```
+sudo journalctl -fu nebula
+```
+
+Refer to the nebula src code directory's README for further instructions on configuring nebula.
+
+## Troubleshooting
+
+### Is nebula up and running?
+
+Run and verify that 
+
+```
+ifconfig
+``` 
+
+shows you an interface with the name `nebula1` being up.
+
+```
+vagrant@generic1:~$ ifconfig nebula1
+nebula1: flags=4305<UP,POINTOPOINT,RUNNING,NOARP,MULTICAST>  mtu 1300
+        inet 10.168.91.210  netmask 255.128.0.0  destination 10.168.91.210
+        inet6 fe80::aeaf:b105:e6dc:936c  prefixlen 64  scopeid 0x20<link>
+        unspec 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00  txqueuelen 500  (UNSPEC)
+        RX packets 2  bytes 168 (168.0 B)
+        RX errors 0  dropped 0  overruns 0  frame 0
+        TX packets 11  bytes 600 (600.0 B)
+        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
+```
+
+### Connectivity
+
+Are you able to ping other boxes on the private nebula network?
+
+The following are the private nebula ip addresses of the vagrant env 
+
+```
+generic1.vagrant [nebula_ip] 10.168.91.210
+generic2.vagrant [nebula_ip] 10.168.91.220 
+lighthouse1.vagrant [nebula_ip] 10.168.91.230
+```
+
+Try pinging generic1.vagrant to and from any other box using its nebula ip above.
+
+Double check the nebula firewall rules under /etc/nebula/config.yml to make sure that connectivity is allowed for your use-case if on a specific port.
+
+```
+vagrant@lighthouse1:~$ grep -A21 firewall /etc/nebula/config.yml 
+firewall:
+  conntrack:
+    tcp_timeout: 12m
+    udp_timeout: 3m
+    default_timeout: 10m
+    max_connections: 100,000
+
+  inbound:
+    - proto: icmp
+      port: any
+      host: any
+    - proto: any
+      port: 22
+      host: any
+    - proto: any
+      port: 53
+      host: any
+
+  outbound:
+    - proto: any
+      port: any
+      host: any
+```