Merge pull request #10 from minitriga/update_version

Update version

Author: minitriga

LICENCE

@@ -0,0 +1,14 @@
+Copyright 2020 Axians UK <[email protected]>
+Axians UK
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -2,9 +2,14 @@
 
 A plugin for [Netbox](https://github.com/netbox-community/netbox) to get power distribution unit Information.
 
-`axians-netbox-plugin-pdu` is using [Easy SNMP](https://easysnmp.readthedocs.io/en/latest/), [Django-RQ](https://github.com/rq/django-rq) and [RQ-Scheduler](https://github.com/rq/rq-scheduler) to display PDU information within Netbox. 
+`axians-netbox-plugin-pdu` is using [Easy SNMP](https://easysnmp.readthedocs.io/en/latest/), [Django-RQ](https://github.com/rq/django-rq) and [RQ-Scheduler](https://github.com/rq/rq-scheduler) to display PDU information within Netbox.
 
 ## Installation
+The plugin is available as a Python package in pypi and can be installed with pip
+
+```
+pip install axians-netbox-plugin-pdu
+```
 
 > The plugin is compatible with NetBox 2.8.1 and higher
 
@@ -20,6 +25,68 @@ PLUGINS = ["axians_netbox_pdu"]
 # }
 ```
 
+There are a number of default settings that can be altered using the following list of settings:
+
+* `schedule`: Boolean (default True). If True, this will enable automatic polling of your PDU Devices.
+* `schedule_interval`: Integer (default 300 seconds). Length of time between each scheduled poll.
+* `snmp_read`: String (default public) SNMP read value for your SNMP enabled PDU's.
+* `snmp_write`: String (default private) SNMP write value for your SNMP enabled PDU's.
+* `rack_view_pdu_devices`: Boolean (default True), if True, the power usage per PDU will be displayed on the rack page.
+* `rack_view_usage_summary`: Boolean (default True), if True, the a summary information tile will appear within the rack page to show true power utilization within the rack.
+* `rack_view_summary_unit`: String (default watts), option to display watts/kilowatts on the rack summary view. If "kilowatts" is used the power usage summary will display in Kilowatts.
+
+## Usage
+### Preparation
+For this plugin to work there must be a new worker added to your Netbox installation. The new worker is a custom scheduler that will schedule the PDU Tasks to run on an interval and utilize the django-rq library.
+
+> You can utilize this library without the automated tasks by feeding Netbox the power usage information via the `axians_netbox_pdu` API.
+
+### Default Environment
+For the standard install please use the included [netbox-pdu.service](contrib/netbox-pdu.service) and install using the standard [Netbox Documentation](https://netbox.readthedocs.io/en/stable/installation/migrating-to-systemd/).
+
+### Docker Environment
+To use within Docker make sure you have a container running that runs the following command: `python manage.py pduschedule`
+
+### Adding a new PDU Configuration
+Once installed and the `pduscheduler` is running you can attach a `PDUConfig` to a DeviceType. To do this you must have a DeviceType configured with PowerOutlets. You can specify the DeviceType, PDU SNMP OID and the Unit. This enables the plugin to know what SNMP OID to collect per DeviceType.
+
+Now a PDUConfig has been created a device must be created with a management IP. Once this is done the plugin can poll the PDU via SNMP and save the power usage.
+
+This can also be done via Bulk Import or via the API.
+
+> If a a PDUConfig is not created for a DeviceType and the Device does not have a Primary IP no data will be collected.
+
+### API
+The plugin includes several endpoints to manage the PDUConfig and PDUStatus.
+
+```
+GET       /api/plugins/pdu/pdu-config/         List PDUConfig
+POST      /api/plugins/pdu/pdu-config/         Create PDUConfig
+PATCH/PUT /api/plugins/pdu/pdu-config/{id}/    Edit a specific PDUConfig
+DELETE /api/plugins/pdu/pdu-config/{id}/       Delete a specific PDUConfig
+
+GET       /api/plugins/pdu/pdu-status/         List PDUStatus
+POST      /api/plugins/pdu/pdu-status/         Create PDUStatus
+PATCH/PUT /api/plugins/pdu/pdu-status/{id}/    Edit a specific PDUStatus
+DELETE /api/plugins/pdu/pdu-status/{id}/       Delete a specific PDUStatus
+```
+
+## Screen Shots
+List of PDUConfig Instances
+![PDUConfig List View](docs/images/PDUConfig_list.png)
+
+Import PDUConfig Instances
+![PDUConfig Import View](docs/images/PDUConfig_import.png)
+
+Edit PDUConfig Instances
+![PDUConfig Edit View](docs/images/PDUConfig_edit.png)
+
+View PDUStatus Device View
+![PDUStatus Device View](docs/images/PDUStatus_device.png)
+
+View PDUStatus Rack View
+![PDUStatus Rack View](docs/images/PDUStatus_rack.png)
+
 ## Contributing
 
 Pull requests are welcomed.
@@ -45,14 +112,14 @@ Each command can be executed with `invoke <command>`. All commands support the a
 ```
 
 
-#### Utility 
+#### Utility
 ```
   cli              Launch a bash shell inside the running NetBox container.
   create-user      Create a new user in django (default: admin), will prompt for password.
   makemigrations   Run Make Migration in Django.
   nbshell          Launch a nbshell session.
 ```
-#### Testing 
+#### Testing
 
 ```
   tests            Run all tests for this plugin.

axians_netbox_pdu/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.0.1"
+__version__ = "0.0.2"
 
 from extras.plugins import PluginConfig
 

axians_netbox_pdu/models.py

@@ -19,7 +19,7 @@ class PDUConfig(models.Model):
     csv_headers = ["device_type", "power_usage_oid", "power_usage_unit"]
 
     def __str__(self):
-        """String representation of an OnboardingTask."""
+        """String representation of an PDUConfig."""
         return f"{self.device_type}"
 
 

axians_netbox_pdu/navigation.py

@@ -12,14 +12,14 @@
                 title="Add",
                 icon_class="fa fa-plus",
                 color=ButtonColorChoices.GREEN,
-                permissions=["netbox_onboarding.add_pduconfig"],
+                permissions=["axians_netbox_pdu.add_pduconfig"],
             ),
             PluginMenuButton(
                 link="plugins:axians_netbox_pdu:pduconfig_import",
                 title="Bulk Add",
                 icon_class="fa fa-download",
                 color=ButtonColorChoices.BLUE,
-                permissions=["netbox_onboarding.add_pduconfig"],
+                permissions=["axians_netbox_pdu.add_pduconfig"],
             ),
         ),
     ),

axians_netbox_pdu/templates/axians_netbox_pdu/device_type_pduconfig.html

@@ -16,10 +16,12 @@
             </tr>
         </tbody>
     </table>
+    {% if perms.axians_netbox_pdu.change_pduconfig %}
     <div class="panel-footer noprint">
         <a href="{% url 'plugins:axians_netbox_pdu:pduconfig_edit' pk=pduconfig.pk %}"
             class="btn btn-xs btn-warning"><span class="glyphicon glyphicon-pencil" aria-hidden="true"></span>
             Edit</a>
         <div class="clearfix"></div>
     </div>
+    {% endif %}
 </div>

contrib/netbox-pdu.service

@@ -0,0 +1,21 @@
+[Unit]
+Description=NetBox Axians PDU Plugin Scheduler
+Documentation=https://github.com/minitriga/netbox-axians-pdu
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+
+User=netbox
+Group=netbox
+WorkingDirectory=/opt/netbox
+
+ExecStart=/opt/netbox/venv/bin/python3 /opt/netbox/netbox/manage.py pduscheduler
+
+Restart=on-failure
+RestartSec=30
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target