From b331bcb93442cba89a5bbf5f71fe789f7312525a Mon Sep 17 00:00:00 2001
From: Solvik <solvik@solvik.fr>
Date: Wed, 17 Jun 2020 17:54:10 +0200
Subject: [PATCH] Better usage infos (#134)

---
 README.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 80 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index e7ccd2a..3d0bc40 100644
--- a/README.md
+++ b/README.md
@@ -32,32 +32,81 @@ The goal is to generate an existing infrastructure on Netbox and have the abilit
 - lldpd
 - lshw
 
-# Known limitations
+## Inventory requirement
+- hpassacli
+- storcli
+- omreport
 
-* The project is only compatible with Linux.
-Since it uses `ethtool` and parses `/sys/` directory, it's not compatible with *BSD distributions.
-* Netbox `>=2.6.0,<=2.6.2` has a caching problem ; if the cache lifetime is too high, the script can get stale data after modification.
-We advise to set `CACHE_TIME` to `0`.
+# Installation
+
+```
+# pip3 install netbox-agent
+```
+
+# Usage
+
+The agent can be run from a shell and get its configuration from either the configuration file or environment variables.
+
+Configuration values are overridden based on the following precedence: command line arguments (might include config file) > environment variables > default config file > defaults.
+
+```
+# netbox_agent -c /etc/netbox_agent.yml --register
+INFO:root:Creating chassis blade (serial: QTFCQ574502EF)
+INFO:root:Creating blade (serial: QTFCQ574502D2) myserver on chassis QTFCQ574502EF
+INFO:root:Setting device (QTFCQ574502D2) new slot on Slot 9 (Chassis QTFCQ574502EF)..
+INFO:root:Interface a8:1e:84:f2:9e:6a not found, creating..
+INFO:root:Creating NIC enp1s0f1 (a8:1e:84:f2:9e:6a) on myserver
+INFO:root:Interface 02:42:7a:89:cf:a4 not found, creating..
+INFO:root:Creating NIC br-07ea1e4a2f0e (02:42:7a:89:cf:a4) on myserver
+INFO:root:Create new IP 172.19.0.1/16 on br-07ea1e4a2f0e
+INFO:root:Interface a8:1e:84:f2:9e:69 not found, creating..
+INFO:root:Creating NIC enp1s0f0 (a8:1e:84:f2:9e:69) on myserver
+INFO:root:Create new IP 42.42.42.42/24 on enp1s0f0
+INFO:root:Create new IP fe80::aa1e:84ff:fef2:9e69/64 on enp1s0f0
+INFO:root:Interface a8:1e:84:cd:9d:d6 not found, creating..
+INFO:root:Creating NIC IPMI (a8:1e:84:cd:9d:d6) on myserver
+INFO:root:Create new IP 10.191.122.10/24 on IPMI
+```
+
+If you need, you can update only specific informations like:
+* Network
+* Inventory
+* Location
+* PSUs
+
+```
+# ip a add 42.42.42.43/24 dev enp1s0f1
+# netbox_agent -c /etc/netbox_agent.yaml --update-network
+INFO:root:Create new IP 42.42.42.43/24 on enp1s0f1
+# netbox_agent --update-inventory
+INFO:root:Creating Disk Samsung SSD 850 S2RBNX0K101698D
+```
 
 # Configuration
 
 ```
+# Netbox configuration
 netbox:
  url: 'http://netbox.internal.company.com'
  token: supersecrettoken
 
+# Network configuration
 network:
+  # Regex to ignore interfaces 
   ignore_interfaces: "(dummy.*|docker.*)"
+  # Regex to ignore IP addresses
   ignore_ips: (127\.0\.0\..*)
-  # enable auto-cabling
+  # enable auto-cabling by parsing LLDP answers
   lldp: true
 
+## Enable virtual machine support 
 # virtual:
 #   # not mandatory, can be guessed
 #   enabled: True
 #   # see https://netbox.company.com/virtualization/clusters/
 #   cluster_name: my_vm_cluster
 
+# Enable datacenter location feature in Netbox
 datacenter_location:
  driver: "cmd:cat /etc/qualification | tr [a-z] [A-Z]"
  regex: "DATACENTER: (?P<datacenter>[A-Za-z0-9]+)"
@@ -67,6 +116,7 @@ datacenter_location:
 # driver: "file:/tmp/datacenter"
 # regex: "(.*)"
 
+# Enable rack location feature in Netbox
 rack_location:
 # driver: 'cmd:lldpctl'
 # match SysName: sw-dist-a1.dc42
@@ -75,6 +125,7 @@ rack_location:
 # driver: "file:/tmp/datacenter"
 # regex: "(.*)"
 
+# Enable local inventory reporting 
 inventory: true
 ```
 
@@ -161,6 +212,27 @@ Feel free to send me a dmidecode output for Supermicro's blade!
 
 * Nothing ATM, feel free to send me a dmidecode or make a PR!
 
-# TODO
+# Known limitations
 
-- [ ] `CustomFields` support with firmware versions for Device (BIOS), RAID Cards and disks
+* The project is only compatible with Linux.
+Since it uses `ethtool` and parses `/sys/` directory, it's not compatible with *BSD distributions.
+* Netbox `>=2.6.0,<=2.6.2` has a caching problem ; if the cache lifetime is too high, the script can get stale data after modification.
+We advise to set `CACHE_TIME` to `0`.
+
+# Developing
+
+If you want to run the agent while adding features or just for debugging purposes
+
+```
+# git clone https://github.com/Solvik/netbox-agent.git
+# cd netbox-agent
+# python3 -m netbox_agent.cli --register
+```
+
+On a personal note, I use the docker image from [netbox-community/netbox-docker](https://github.com/netbox-community/netbox-docker)
+```
+# git clone https://github.com/netbox-community/netbox-docker
+# cd netbox-docker
+# docker-compose pull
+# docker-compose up 
+```