X-Git-Url: https://gerrit.opnfv.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Frelease%2Fuserguide%2Ffeature.userguide.rst;h=acef42320ece6c04249c31b3315474a0bd9041ed;hb=6491d7c069c1443c437bf3a55e3ca014bad30a92;hp=099d8e27ec7a4aef8b63bf14d43b63536fe978a2;hpb=52a749bd73579f521caae478f6825e8a1abd4005;p=barometer.git diff --git a/docs/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst index 099d8e27..acef4232 100644 --- a/docs/release/userguide/feature.userguide.rst +++ b/docs/release/userguide/feature.userguide.rst @@ -6,10 +6,6 @@ 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 @@ -321,7 +317,7 @@ To configure some hugepages: $ 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: @@ -380,6 +376,18 @@ Building and installing *jevents* library: $ 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 @@ -407,6 +415,23 @@ include: ReportSoftwareEvents true +If you want to monitor Intel CPU specific CPU events, make sure to enable the +additional two options shown below: + +.. code:: bash + + + 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" + + +.. 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 @@ -475,7 +500,7 @@ 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 @@ -514,41 +539,24 @@ Remove old version of OpenIPMI library: $ 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 @@ -564,16 +572,13 @@ Clone and install the collectd IPMI plugin: .. 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: @@ -582,7 +587,9 @@ To configure the IPMI plugin you need to modify the file to include: LoadPlugin ipmi - SELEnabled true # only feat_ipmi_events branch supports this + + SELEnabled true # only feat_ipmi_events branch supports this + .. note:: @@ -590,8 +597,7 @@ To configure the IPMI plugin you need to modify the file to include: 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: @@ -681,7 +687,7 @@ Clone and install the collectd mcelog plugin: .. 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 @@ -699,11 +705,15 @@ include: Interval 1 - McelogClientSocket "/var/run/mcelog-client" + + McelogClientSocket "/var/run/mcelog-client" + PersistentNotification false + + #McelogLogfile "/var/log/mcelog" 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: @@ -733,6 +743,7 @@ Then you can run the mcelog test suite with 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. @@ -911,7 +922,7 @@ ovs_pmd_stat.sh calls the script for OVS PMD stats application with its argument SNMP Agent Plugin ^^^^^^^^^^^^^^^^^ -Repo: https://github.com/maryamtahhan/collectd/ +Repo: https://github.com/collectd/collectd Branch: master @@ -924,9 +935,11 @@ On Centos 7: .. 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: @@ -967,12 +980,14 @@ Configure snmpd as a service: $ 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: @@ -981,13 +996,29 @@ 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 @@ -1013,6 +1044,15 @@ memAvailReal OID to value represented as free memory type of memory 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 @@ -1022,14 +1062,16 @@ memAvailReal OID to value represented as free memory type of memory plugin: 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 @@ -1039,14 +1081,18 @@ On Centos, install the dependencies: .. 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)* @@ -1160,7 +1206,9 @@ statistics are disabled. They can be enabled with ``ExtraStats`` option. 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -1198,9 +1246,9 @@ Reload 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 @@ -1268,6 +1316,41 @@ To see this demo in action please checkout: `Barometer OPNFV Summit demo`_ 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 @@ -1283,3 +1366,7 @@ References .. _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