Browse Source

Merge "add user guide documentation files"

Jenkins 3 years ago
parent
commit
377a6c27c4

+ 7
- 0
doc/content/appendix.rst View File

@@ -0,0 +1,7 @@
1
+========
2
+Appendix
3
+========
4
+
5
+`Zabbix 2.4 documentation - SNMP traps <https://www.zabbix.com/documentation/2.4/manual/config/items/itemtypes/snmptrap>`_
6
+
7
+`Zabbix 2.4 documentation - Templates <https://www.zabbix.com/documentation/2.4/manual/config/templates>`_

+ 26
- 0
doc/content/description.rst View File

@@ -0,0 +1,26 @@
1
+==================================
2
+SNMP trap daemon for Zabbix plugin
3
+==================================
4
+
5
+This plugin extends Zabbix plugin functionality by adding ability to receive
6
+SNMP traps from management network and pass them to Zabbix. For more
7
+information about networks, see the `Logical Networks <https://
8
+docs.mirantis.com/openstack/fuel/fuel-6.1/reference-architecture.html
9
+#logical-networks>`_ section of MOS documentation. The plugins installs
10
+snmptrapd daemon for receiving and snmptt software for parsing and passing
11
+traps to Zabbix. This plugin does not provide any additional features from user
12
+point of view. It was designed as a base for other plugins which needs to
13
+analyze SNMP traps incoming from for example network and storage hardware like
14
+network switches or storage arrays. By using this plugin user can easily create
15
+additional plugins to add monitoring of SNMP traps specific for their hardware.
16
+
17
+Requirements
18
+============
19
+
20
+====================== ===============
21
+Requirement            Version/Comment
22
+====================== ===============
23
+Fuel                   6.1
24
+Zabbix plugin for Fuel 1.0.0
25
+====================== ===============
26
+

+ 120
- 0
doc/content/guide.rst View File

@@ -0,0 +1,120 @@
1
+==========
2
+User Guide
3
+==========
4
+
5
+Environment configuration
6
+=========================
7
+
8
+1. Create an environment. For more information about environment creation, see
9
+   `Mirantis OpenStack User Guide <http://docs.mirantis.com/openstack/fuel
10
+   /fuel-6.1/user-guide.html#create-a-new-openstack-environment>`_.
11
+2. Enable and configure Zabbix plugin for Fuel. For instructions, see Zabbix
12
+   Plugin Guide in the `Fuel Plugins Catalog <https://www.mirantis.com
13
+   /products/openstack-drivers-and-plugins/fuel-plugins/>`_.
14
+3. Open *Settings* tab of the Fuel web UI and scroll the page down. Select the
15
+   plugin checkbox and set *SNMP community* parameter:
16
+
17
+   .. image:: images/settings.png
18
+
19
+   You could see default value by clicking on the eye icon. It is highly
20
+   recommended to change default SNMP community, because it is used to
21
+   authorize incoming SNMP traps.
22
+4. Adjust other environment settings to your requirements and deploy the
23
+   environment. For more information, see
24
+   `Mirantis OpenStack User Guide <http://docs.mirantis.com/openstack/fuel
25
+   /fuel-6.1/user-guide.html#create-a-new-openstack-environment>`_.
26
+
27
+Environment validation
28
+======================
29
+
30
+After a successful deployment, all Controller Nodes should have the following:
31
+
32
+1. snmptrapd daemon running and listening on UDP/162 port on the VIP management
33
+   address.
34
+2. snmptrapd daemon configured to pass all SNMP traps to snmptt handler.
35
+3. snmptt daemon running which parse SNMP traps and stores them in a log file
36
+   in a format accepted by Zabbix.
37
+4. Zabbix SNMPTrapper processes running which reads SNMP traps from the log
38
+   file (only on node on which Zabbix Server is running).
39
+
40
+To test if everything is installed and configured properly, follow these steps:
41
+
42
+1. Generate a test SNMP trap running following command from any node::
43
+
44
+       [root@node-46 ~]# snmptrap -v 2c -c <SNMP_community> <management_VIP_address> "" .1.3.6.1.4.1.8072.2.3.0.1
45
+
46
+   where:
47
+
48
+   *<SNMP_ community>*
49
+
50
+       It is set in the SNMP trap daemon for Zabbix plugin Settings in Fuel UI:
51
+
52
+   .. image:: images/settings.png
53
+
54
+   *<management_VIP_address>*
55
+
56
+       If you don’t know the address, run the following command on any node::
57
+
58
+           [root@node-46 ~]# grep management_vip /etc/astute.yaml
59
+
60
+       You should get the required VIP in the output::
61
+
62
+           management_vip: 192.168.0.1
63
+
64
+
65
+2. After several seconds of running the snmptrap command you should see a line
66
+   in the Zabbix Server log file similar to this one::
67
+
68
+       [root@node-45 ~]# grep netSnmpExampleHeartbeatNotification \ /var/log/zabbix/zabbix_server.log
69
+       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
70
+
71
+   This is a proof that test SNMP trap has been received and passed to Zabbix.
72
+   It is “unmatched” for Zabbix because there is no configuration for this trap
73
+   in Zabbix (this trap is for testing purposes only).
74
+
75
+
76
+How to use SNMP trap daemon for Zabbix plugin
77
+=============================================
78
+
79
+As noted above, with this plugin you can easily create additional plugins to
80
+add monitoring of SNMP traps specific for your hardware. To achieve this,
81
+the following tasks should be done by additional plugin:
82
+
83
+1. On all Controller nodes, add SNMP traps to snmptt configuration:
84
+
85
+   a. Create configuration file in */etc/snmp/snmptt.conf.d/* directory, for
86
+      example *emc.conf*, with SNMP traps defined, for more information, see
87
+      `snmptt documentation <http://snmptt.sourceforge.net/docs/snmptt.shtml
88
+      #SNMPTT.CONF-Configuration-file-format>`_.
89
+   b. Add the file (absolute path) to *snmptt_conf_files* parameter in
90
+      *snmptt.ini* file.
91
+   c. Reload snmptt service.
92
+
93
+2. Create a Zabbix monitoring Template and export it to a file. For more
94
+   information, see `Templates section in the Zabbix documentation <https://
95
+   www.zabbix.com/documentation/2.4/manual/config/templates>`_.
96
+3. From Primary Controller node configure Zabbix:
97
+
98
+   a. Copy created Template file to the Primary Controller node.
99
+   b. Import the Template to Zabbix using *plugin_zabbix_configuration_import*
100
+      resource.
101
+   c. Optionally, create a Host group in Zabbix using *plugin_zabbix_hostgroup*
102
+      resource.
103
+   d. Create Host in Zabbix using *plugin_zabbix_host* resource setting
104
+      appropriate name, IP and group.
105
+   e. Link the Template with the Host using *plugin_zabbix_template_link*
106
+      resource.
107
+
108
+There are two plugins in the `Fuel Plugins Catalog <https://www.mirantis.com
109
+/products/openstack-drivers-and-plugins/fuel-plugins/>`_ you can refer to as an
110
+example:
111
+
112
+1. EMC hardware monitoring extension for Zabbix plugin.
113
+2. Extreme Networks hardware monitoring extension for Zabbix plugin.
114
+
115
+These plugins do all the tasks mentioned above and have their own Zabbix
116
+monitoring Templates. You can simply copy one of these plugins and adjust SNMP
117
+traps configuration to your hardware. For more information about Fuel Plugins
118
+development, see `Fuel Plugins wiki page <https://wiki.openstack.org/wiki/Fuel
119
+/Plugins>`_.
120
+

+ 34
- 0
doc/content/installation.rst View File

@@ -0,0 +1,34 @@
1
+==================
2
+Installation Guide
3
+==================
4
+
5
+SNMP trap daemon for Zabbix plugin installation
6
+===============================================
7
+
8
+To install SNMP trap daemon for Zabbix plugin, follow these steps:
9
+
10
+1. Download and install the Zabbix plugin for Fuel from the
11
+   `Fuel Plugins Catalog <https://www.mirantis.com/products/
12
+   openstack-drivers-and-plugins/fuel-plugins/>`_
13
+2. Download the SNMP trap daemon for Zabbix plugin from the
14
+   `Fuel Plugins Catalog <https://www.mirantis.com/products/
15
+   openstack-drivers-and-plugins/fuel-plugins/>`_
16
+3. Copy the plugin on already installed Fuel Master node; ssh can be used for
17
+   that. If you do not have the Fuel Master node yet, see `Quick Start Guide
18
+   <https://software.mirantis.com/quick-start/>`_::
19
+
20
+    # scp zabbix_snmptrapd-1.0-1.0.0-1.noarch.rpm root@<The_Fuel_Master_node_IP>:/tmp
21
+
22
+4. Log into the Fuel Master node. Install the plugin::
23
+
24
+    # cd /tmp
25
+    # fuel plugins --install zabbix_snmptrapd-1.0-1.0.0-1.noarch.rpm
26
+
27
+5. Check if the plugin was installed successfully::
28
+
29
+    # fuel plugins
30
+    id | name                      | version  | package_version
31
+    ---|---------------------------|----------|----------------
32
+    1  | zabbix_monitoring         | 1.0.0    | 2.0.0
33
+    2  | zabbix_snmptrapd          | 1.0.0    | 2.0.0
34
+

+ 32
- 0
doc/content/licenses.rst View File

@@ -0,0 +1,32 @@
1
+===================
2
+Components licenses
3
+===================
4
+
5
+rpm packages
6
+============
7
+
8
+====================== ============
9
+Name                   License
10
+====================== ============
11
+net-snmp               BSD
12
+net-snmp-libs          BSD
13
+net-snmp-perl          BSD
14
+snmptt                 GPLv2+
15
+perl-Config-IniFiles   GPL+
16
+perl-Crypt-DES         BSD
17
+perl-Digest-HMAC       GPL+
18
+perl-Digest-SHA1       GPL+
19
+perl-IO-stringy        GPL+
20
+perl-List-MoreUtils    GPL+
21
+perl-Net-SNMP          GPL+
22
+====================== ============
23
+
24
+puppet modules
25
+==============
26
+
27
+====================== ==============
28
+Name                   License
29
+====================== ==============
30
+snmp                   Apache 2.0
31
+====================== ==============
32
+

+ 19
- 0
doc/content/terms.rst View File

@@ -0,0 +1,19 @@
1
+=====================================
2
+Key terms, acronyms and abbreviations
3
+=====================================
4
+
5
+Zabbix
6
+    An enterprise open source monitoring solution for networks and
7
+    applications. It is designed to monitor and track the status of various
8
+    network services,servers, and other network hardware.
9
+
10
+VIP
11
+    Virtual IP Adress.
12
+
13
+SNMP trap
14
+    A message which is send from agent (for example, from network switch) to
15
+    monitoring manager.
16
+
17
+SNMP community
18
+    A password which is used for incoming SNMP traps authorization.
19
+

BIN
doc/images/settings.png View File


+ 15
- 0
doc/user_guide.rst View File

@@ -0,0 +1,15 @@
1
+***********************************************
2
+Guide to the SNMP trap daemon for Zabbix plugin
3
+***********************************************
4
+
5
+This document provides instructions for installing, configuring and using
6
+SNMP trap daemon for Zabbix plugin.
7
+
8
+.. contents::
9
+.. include:: content/terms.rst
10
+.. include:: content/description.rst
11
+.. include:: content/installation.rst
12
+.. include:: content/guide.rst
13
+.. include:: content/appendix.rst
14
+.. include:: content/licenses.rst
15
+

Loading…
Cancel
Save