OPNFV Barometer User Guide
===================================
-.. contents::
- :depth: 3
- :local:
-
Barometer collectd plugins description
---------------------------------------
.. Describe the specific features and how it is realised in the scenario in a brief manner
$ sudo mkdir -p /mnt/huge
$ sudo mount -t hugetlbfs nodev /mnt/huge
- $ sudo echo 14336 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
+ $ sudo bash -c "echo 14336 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages"
Building and installing collectd:
$ make
$ sudo make install
+Download the Hardware Events that are relevant to your CPU, download the appropriate
+CPU event list json file:
+
+.. code:: bash
+
+ $ wget https://raw.githubusercontent.com/andikleen/pmu-tools/master/event_download.py
+ $ python event_download.py
+
+This will download the json files to the location: $HOME/.cache/pmu-events/. If you don't want to
+download these files to the aforementioned location, set the environment variable XDG_CACHE_HOME to
+the location you want the files downloaded to.
+
Building and installing collectd:
.. code:: bash
ReportSoftwareEvents true
</Plugin>
+If you want to monitor Intel CPU specific CPU events, make sure to enable the
+additional two options shown below:
+
+.. code:: bash
+
+ <Plugin intel_pmu>
+ ReportHardwareCacheEvents true
+ ReportKernelPMUEvents true
+ ReportSoftwareEvents true
+ EventList "$HOME/.cache/pmu-events/GenuineIntel-6-2D-core.json"
+ HardwareEvents "L2_RQSTS.CODE_RD_HIT,L2_RQSTS.CODE_RD_MISS" "L2_RQSTS.ALL_CODE_RD"
+ </Plugin>
+
+.. note::
+ If you set XDG_CACHE_HOME to anything other than the variable above - you will need to modify
+ the path for the EventList configuration.
+
For more information on the plugin parameters, please see:
https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
IPMI Plugin
^^^^^^^^^^^^
-Repo: https://github.com/maryamtahhan/collectd
+Repo: https://github.com/collectd/collectd
Branch: feat_ipmi_events, feat_ipmi_analog
$ sudo yum remove OpenIPMI ipmitool
-Download OpenIPMI library sources:
+Build and install OpenIPMI library:
.. code:: bash
$ git clone https://git.code.sf.net/p/openipmi/code openipmi-code
$ cd openipmi-code
-
-Patch the OpenIPMI pkg-config file to provide correct compilation flags
-for collectd IPMI plugin:
-
-.. code:: diff
-
- diff --git a/OpenIPMIpthread.pc.in b/OpenIPMIpthread.pc.in
- index 59b52e5..fffa0d0 100644
- --- a/OpenIPMIpthread.pc.in
- +++ b/OpenIPMIpthread.pc.in
- @@ -6,6 +6,6 @@ includedir=@includedir@
- Name: OpenIPMIpthread
- Description: Pthread OS handler for OpenIPMI
- Version: @VERSION@
- -Requires: OpenIPMI pthread
- +Requires: OpenIPMI
- Libs: -L${libdir} -lOpenIPMIutils -lOpenIPMIpthread
- -Cflags: -I${includedir}
- +Cflags: -I${includedir} -pthread
-
-Build and install OpenIPMI library:
-
-.. code:: bash
-
$ autoreconf --install
$ ./configure --prefix=/usr
$ make
$ sudo make install
+Add the directory containing ``OpenIPMI*.pc`` files to the ``PKG_CONFIG_PATH``
+environment variable:
+
+.. code:: bash
+
+ export PKG_CONFIG_PATH=/usr/lib/pkgconfig
+
Enable IPMI support in the kernel:
.. code:: bash
.. code:: bash
- $ git clone https://github.com/maryamtahhan/collectd
+ $ git clone https://github.com/collectd/collectd
$ cd collectd
- $ git checkout $BRANCH
$ ./build.sh
$ ./configure --enable-syslog --enable-logfile --enable-debug
$ make
$ sudo make install
-Where $BRANCH is feat_ipmi_events or feat_ipmi_analog.
-
This will install collectd to default folder ``/opt/collectd``. The collectd
configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``.
To configure the IPMI plugin you need to modify the file to include:
LoadPlugin ipmi
<Plugin ipmi>
- SELEnabled true # only feat_ipmi_events branch supports this
+ <Instance "local">
+ SELEnabled true # only feat_ipmi_events branch supports this
+ </Instance>
</Plugin>
.. note::
dispatch the values to collectd and send SEL notifications.
For more information on the IPMI plugin parameters and SEL feature configuration,
-please see:
-https://github.com/maryamtahhan/collectd/blob/feat_ipmi_events/src/collectd.conf.pod
+please see: https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
Extended analog sensors support doesn't require additional configuration. The usual
collectd IPMI documentation can be used:
.. code:: bash
- $ git clone https://github.com/maryamtahhan/collectd
+ $ git clone https://github.com/collectd/collectd
$ cd collectd
$ ./build.sh
$ ./configure --enable-syslog --enable-logfile --enable-debug
Interval 1
</LoadPlugin>
<Plugin mcelog>
- McelogClientSocket "/var/run/mcelog-client"
+ <Memory>
+ McelogClientSocket "/var/run/mcelog-client"
+ PersistentNotification false
+ </Memory>
+ #McelogLogfile "/var/log/mcelog"
</Plugin>
For more information on the plugin parameters, please see:
-https://github.com/maryamtahhan/collectd/blob/feat_ras/src/collectd.conf.pod
+https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
Simulating a Machine Check Exception can be done in one of 3 ways:
This will inject different classes of errors and check that the mcelog triggers
runs. There will be some kernel messages about page offlining attempts. The
test will also lose a few pages of memory in your system (not significant).
+
.. note::
This test will kill any running mcelog, which needs to be restarted
manually afterwards.
SNMP Agent Plugin
^^^^^^^^^^^^^^^^^
-Repo: https://github.com/maryamtahhan/collectd/
+Repo: https://github.com/collectd/collectd
Branch: master
.. code:: bash
$ sudo yum install net-snmp net-snmp-libs net-snmp-utils net-snmp-devel
- $ systemctl start snmpd.service
+ $ sudo systemctl start snmpd.service
-Or build from source
+go to the `snmp configuration`_ steps.
+
+From source:
Clone and build net-snmp:
$ systemctl enable snmpd.service
$ systemctl start snmpd.service
+.. _`snmp configuration`:
+
Add the following line to snmpd.conf configuration file
-"/usr/share/snmp/snmpd.conf" to make all OID tree visible for SNMP clients:
+``/etc/snmp/snmpd.conf`` to make all OID tree visible for SNMP clients:
.. code:: bash
- view systemonly included .1
+ view systemview included .1
To verify that SNMP is working you can get IF-MIB table using SNMP client
to view the list of Linux interfaces:
$ snmpwalk -v 2c -c public localhost IF-MIB::interfaces
+Get the default MIB location:
+
+.. code:: bash
+
+ $ net-snmp-config --default-mibdirs
+ /opt/stack/.snmp/mibs:/usr/share/snmp/mibs
+
+Install Intel specific MIBs (if needed) into location received by
+``net-snmp-config`` command (e.g. ``/usr/share/snmp/mibs``).
+
+.. code:: bash
+
+ $ git clone https://gerrit.opnfv.org/gerrit/barometer.git
+ $ sudo cp -f barometer/mibs/*.txt /usr/share/snmp/mibs/
+ $ sudo systemctl restart snmpd.service
+
Clone and install the collectd snmp_agent plugin:
.. code:: bash
- $ git clone https://github.com/maryamtahhan/collectd
+ $ cd ~
+ $ git clone https://github.com/collectd/collectd
$ cd collectd
- $ git checkout feat_snmp
$ ./build.sh
$ ./configure --enable-syslog --enable-logfile --enable-debug --enable-snmp --with-libnetsnmp
$ make
</Data>
</Plugin>
+
+The ``snmpwalk`` command can be used to validate the collectd configuration:
+
+.. code:: bash
+
+ $ snmpwalk -v 2c -c public localhost 1.3.6.1.4.1.2021.4.6.0
+ UCD-SNMP-MIB::memAvailReal.0 = INTEGER: 135237632 kB
+
+
**Limitations**
* Object instance with Counter64 type is not supported in SNMPv1. When GetNext
retreived using standard IF-MIB tables.
For more information on the plugin parameters, please see:
-https://github.com/maryamtahhan/collectd/blob/feat_snmp/src/collectd.conf.pod
+https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
For more details on AgentX subagent, please see:
http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/
+.. _virt-plugin:
+
virt plugin
^^^^^^^^^^^^
-Repo: https://github.com/maryamtahhan/collectd
+Repo: https://github.com/collectd/collectd
Branch: master
.. code:: bash
- $ sudo yum install libxml2-dev libpciaccess-devel yajl-devel device-mapper-devel
+ $ sudo yum install libxml2-devel libpciaccess-devel yajl-devel device-mapper-devel
Install libvirt:
-libvirt version in package manager might be quite old and offer only limited
-functionality. Hence, building and installing libvirt from sources is recommended.
-Detailed instructions can bet found at:
-https://libvirt.org/compiling.html
+.. note:: libvirt version in package manager might be quite old and offer only
+ limited functionality. Hence, building and installing libvirt from sources
+ is recommended. Detailed instructions can bet found at:
+ https://libvirt.org/compiling.html
+
+.. code:: bash
+
+ $ sudo yum install libvirt-devel
Certain metrics provided by the plugin have a requirement on a minimal version of
the libvirt API. *File system information* statistics require a *Guest Agent (GA)*
</Plugin>
For more information on the plugin parameters, please see:
-https://github.com/maryamtahhan/collectd/blob/feat_libvirt_upstream/src/collectd.conf.pod
+https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
+
+.. _install-collectd-as-a-service:
Installing collectd as a service
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Additional useful plugins
^^^^^^^^^^^^^^^^^^^^^^^^^^
-* **Exec Plugin** : Can be used to show you when notifications are being
- generated by calling a bash script that dumps notifications to file. (handy
- for debug). Modify /opt/collectd/etc/collectd.conf:
+**Exec Plugin** : Can be used to show you when notifications are being
+generated by calling a bash script that dumps notifications to file. (handy
+for debug). Modify /opt/collectd/etc/collectd.conf:
.. code:: bash
For more information on configuring and installing OpenStack plugins for
collectd, check out the `collectd-ceilometer-plugin GSG`_.
+Security
+^^^^^^^^^
+* AAA – on top of collectd there secure agents like SNMP V3, Openstack agents
+ etc. with their own AAA methods.
+
+* Collectd runs as a daemon with root permissions.
+
+* The `Exec plugin`_ allows the execution of external programs but counters the security
+ concerns by:
+
+ * Ensuring that only one instance of the program is executed by collectd at any time
+ * Forcing the plugin to check that custom programs are never executed with superuser
+ privileges.
+
+* Protection of Data in flight:
+
+ * It's recommend to use a minimum version of 4.7 of the Network plugin which provides
+ the possibility to cryptographically sign or encrypt the network traffic.
+ * Write Redis plugin or the Write MongoDB plugin are recommended to store the data.
+ * For more information, please see: https://collectd.org/wiki/index.php?title=Networking_introduction
+
+* Known vulnerabilities include:
+
+ * https://www.cvedetails.com/vulnerability-list/vendor_id-11242/Collectd.html
+
+ * `CVE-2017-7401`_ fixed https://github.com/collectd/collectd/issues/2174 in Version 5.7.2.
+ * `CVE-2016-6254`_ fixed https://mailman.verplant.org/pipermail/collectd/2016-July/006838.html
+ in Version 5.4.3.
+ * `CVE-2010-4336`_ fixed https://mailman.verplant.org/pipermail/collectd/2010-November/004277.html
+ in Version 4.10.2.
+
+ * http://www.cvedetails.com/product/20310/Collectd-Collectd.html?vendor_id=11242
+
+* It's recommended to only use collectd plugins from signed packages.
+
References
^^^^^^^^^^^
.. [1] https://collectd.org/wiki/index.php/Naming_schema
.. _aodh plugin: https://github.com/openstack/collectd-ceilometer-plugin/tree/stable/ocata/
.. _collectd-ceilometer-plugin GSG: https://github.com/openstack/collectd-ceilometer-plugin/blob/master/doc/source/GSG.rst
.. _grafana guide: https://wiki.opnfv.org/display/fastpath/Installing+and+configuring+InfluxDB+and+Grafana+to+display+metrics+with+collectd
+.. _CVE-2017-7401: https://www.cvedetails.com/cve/CVE-2017-7401/
+.. _CVE-2016-6254: https://www.cvedetails.com/cve/CVE-2016-6254/
+.. _CVE-2010-4336: https://www.cvedetails.com/cve/CVE-2010-4336/
+.. _Exec plugin: https://collectd.org/wiki/index.php/Plugin:Exec
Code Review / barometer.git / blobdiff