diff --git a/doc/content/appendix.rst b/doc/content/appendix.rst new file mode 100644 index 0000000..6517d99 --- /dev/null +++ b/doc/content/appendix.rst @@ -0,0 +1,7 @@ +======== +Appendix +======== + +`Zabbix 2.4 documentation - SNMP traps `_ + +`Zabbix 2.4 documentation - Templates `_ diff --git a/doc/content/description.rst b/doc/content/description.rst new file mode 100644 index 0000000..4ca4ce3 --- /dev/null +++ b/doc/content/description.rst @@ -0,0 +1,26 @@ +================================== +SNMP trap daemon for Zabbix plugin +================================== + +This plugin extends Zabbix plugin functionality by adding ability to receive +SNMP traps from management network and pass them to Zabbix. For more +information about networks, see the `Logical Networks `_ section of MOS documentation. The plugins installs +snmptrapd daemon for receiving and snmptt software for parsing and passing +traps to Zabbix. This plugin does not provide any additional features from user +point of view. It was designed as a base for other plugins which needs to +analyze SNMP traps incoming from for example network and storage hardware like +network switches or storage arrays. By using this plugin user can easily create +additional plugins to add monitoring of SNMP traps specific for their hardware. + +Requirements +============ + +====================== =============== +Requirement Version/Comment +====================== =============== +Fuel 6.1 +Zabbix plugin for Fuel 1.0.0 +====================== =============== + diff --git a/doc/content/guide.rst b/doc/content/guide.rst new file mode 100644 index 0000000..47c68c5 --- /dev/null +++ b/doc/content/guide.rst @@ -0,0 +1,120 @@ +========== +User Guide +========== + +Environment configuration +========================= + +1. Create an environment. For more information about environment creation, see + `Mirantis OpenStack User Guide `_. +2. Enable and configure Zabbix plugin for Fuel. For instructions, see Zabbix + Plugin Guide in the `Fuel Plugins Catalog `_. +3. Open *Settings* tab of the Fuel web UI and scroll the page down. Select the + plugin checkbox and set *SNMP community* parameter: + + .. image:: images/settings.png + + You could see default value by clicking on the eye icon. It is highly + recommended to change default SNMP community, because it is used to + authorize incoming SNMP traps. +4. Adjust other environment settings to your requirements and deploy the + environment. For more information, see + `Mirantis OpenStack User Guide `_. + +Environment validation +====================== + +After a successful deployment, all Controller Nodes should have the following: + +1. snmptrapd daemon running and listening on UDP/162 port on the VIP management + address. +2. snmptrapd daemon configured to pass all SNMP traps to snmptt handler. +3. snmptt daemon running which parse SNMP traps and stores them in a log file + in a format accepted by Zabbix. +4. Zabbix SNMPTrapper processes running which reads SNMP traps from the log + file (only on node on which Zabbix Server is running). + +To test if everything is installed and configured properly, follow these steps: + +1. Generate a test SNMP trap running following command from any node:: + + [root@node-46 ~]# snmptrap -v 2c -c "" .1.3.6.1.4.1.8072.2.3.0.1 + + where: + + ** + + It is set in the SNMP trap daemon for Zabbix plugin Settings in Fuel UI: + + .. image:: images/settings.png + + ** + + If you don’t know the address, run the following command on any node:: + + [root@node-46 ~]# grep management_vip /etc/astute.yaml + + You should get the required VIP in the output:: + + management_vip: 192.168.0.1 + + +2. After several seconds of running the snmptrap command you should see a line + in the Zabbix Server log file similar to this one:: + + [root@node-45 ~]# grep netSnmpExampleHeartbeatNotification \ /var/log/zabbix/zabbix_server.log + 10730:20150611:182933.176 unmatched trap received from [192.168.0.4]: 18:29:27 2015/06/11 .1.3.6.1.4.1.8072.2.3.0.1 Normal "Status Events" node-46.domain.tld - netSnmpExampleHeartbeatNotification + + This is a proof that test SNMP trap has been received and passed to Zabbix. + It is “unmatched” for Zabbix because there is no configuration for this trap + in Zabbix (this trap is for testing purposes only). + + +How to use SNMP trap daemon for Zabbix plugin +============================================= + +As noted above, with this plugin you can easily create additional plugins to +add monitoring of SNMP traps specific for your hardware. To achieve this, +the following tasks should be done by additional plugin: + +1. On all Controller nodes, add SNMP traps to snmptt configuration: + + a. Create configuration file in */etc/snmp/snmptt.conf.d/* directory, for + example *emc.conf*, with SNMP traps defined, for more information, see + `snmptt documentation `_. + b. Add the file (absolute path) to *snmptt_conf_files* parameter in + *snmptt.ini* file. + c. Reload snmptt service. + +2. Create a Zabbix monitoring Template and export it to a file. For more + information, see `Templates section in the Zabbix documentation `_. +3. From Primary Controller node configure Zabbix: + + a. Copy created Template file to the Primary Controller node. + b. Import the Template to Zabbix using *plugin_zabbix_configuration_import* + resource. + c. Optionally, create a Host group in Zabbix using *plugin_zabbix_hostgroup* + resource. + d. Create Host in Zabbix using *plugin_zabbix_host* resource setting + appropriate name, IP and group. + e. Link the Template with the Host using *plugin_zabbix_template_link* + resource. + +There are two plugins in the `Fuel Plugins Catalog `_ you can refer to as an +example: + +1. EMC hardware monitoring extension for Zabbix plugin. +2. Extreme Networks hardware monitoring extension for Zabbix plugin. + +These plugins do all the tasks mentioned above and have their own Zabbix +monitoring Templates. You can simply copy one of these plugins and adjust SNMP +traps configuration to your hardware. For more information about Fuel Plugins +development, see `Fuel Plugins wiki page `_. + diff --git a/doc/content/installation.rst b/doc/content/installation.rst new file mode 100644 index 0000000..70b5183 --- /dev/null +++ b/doc/content/installation.rst @@ -0,0 +1,34 @@ +================== +Installation Guide +================== + +SNMP trap daemon for Zabbix plugin installation +=============================================== + +To install SNMP trap daemon for Zabbix plugin, follow these steps: + +1. Download and install the Zabbix plugin for Fuel from the + `Fuel Plugins Catalog `_ +2. Download the SNMP trap daemon for Zabbix plugin from the + `Fuel Plugins Catalog `_ +3. Copy the plugin on already installed Fuel Master node; ssh can be used for + that. If you do not have the Fuel Master node yet, see `Quick Start Guide + `_:: + + # scp zabbix_snmptrapd-1.0-1.0.0-1.noarch.rpm root@:/tmp + +4. Log into the Fuel Master node. Install the plugin:: + + # cd /tmp + # fuel plugins --install zabbix_snmptrapd-1.0-1.0.0-1.noarch.rpm + +5. Check if the plugin was installed successfully:: + + # fuel plugins + id | name | version | package_version + ---|---------------------------|----------|---------------- + 1 | zabbix_monitoring | 1.0.0 | 2.0.0 + 2 | zabbix_snmptrapd | 1.0.0 | 2.0.0 + diff --git a/doc/content/licenses.rst b/doc/content/licenses.rst new file mode 100644 index 0000000..8b6482e --- /dev/null +++ b/doc/content/licenses.rst @@ -0,0 +1,32 @@ +=================== +Components licenses +=================== + +rpm packages +============ + +====================== ============ +Name License +====================== ============ +net-snmp BSD +net-snmp-libs BSD +net-snmp-perl BSD +snmptt GPLv2+ +perl-Config-IniFiles GPL+ +perl-Crypt-DES BSD +perl-Digest-HMAC GPL+ +perl-Digest-SHA1 GPL+ +perl-IO-stringy GPL+ +perl-List-MoreUtils GPL+ +perl-Net-SNMP GPL+ +====================== ============ + +puppet modules +============== + +====================== ============== +Name License +====================== ============== +snmp Apache 2.0 +====================== ============== + diff --git a/doc/content/terms.rst b/doc/content/terms.rst new file mode 100644 index 0000000..9ea38b9 --- /dev/null +++ b/doc/content/terms.rst @@ -0,0 +1,19 @@ +===================================== +Key terms, acronyms and abbreviations +===================================== + +Zabbix + An enterprise open source monitoring solution for networks and + applications. It is designed to monitor and track the status of various + network services,servers, and other network hardware. + +VIP + Virtual IP Adress. + +SNMP trap + A message which is send from agent (for example, from network switch) to + monitoring manager. + +SNMP community + A password which is used for incoming SNMP traps authorization. + diff --git a/doc/images/settings.png b/doc/images/settings.png new file mode 100644 index 0000000..07dfce7 Binary files /dev/null and b/doc/images/settings.png differ diff --git a/doc/user_guide.rst b/doc/user_guide.rst new file mode 100644 index 0000000..8ca6a5a --- /dev/null +++ b/doc/user_guide.rst @@ -0,0 +1,15 @@ +*********************************************** +Guide to the SNMP trap daemon for Zabbix plugin +*********************************************** + +This document provides instructions for installing, configuring and using +SNMP trap daemon for Zabbix plugin. + +.. contents:: +.. include:: content/terms.rst +.. include:: content/description.rst +.. include:: content/installation.rst +.. include:: content/guide.rst +.. include:: content/appendix.rst +.. include:: content/licenses.rst +