.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt ========= EXT: SNMP ========= :Author: Kasper Skårhøj :Created: 2002-11-01T00:32:00 :Changed by: Rainer Kuhn :Changed: 2005-06-10T14:26:47 :Author: Rainer Kuhn :Email: kuhn@punkt.de :Info 3: :Info 4: .. _EXT-SNMP: EXT: SNMP ========= Extension Key: **pt\_snmp** Copyright 2004-2005, Rainer Kuhn, revised for version 1.0.0, 2005-06-10 **Extension development sponsored by punkt.de GmbH (http://punkt.de)** This document is published under the Open Content License available from http://www.opencontent.org/opl.shtml The content of this document is related to TYPO3 \- a GNU/GPL CMS/Framework available from www.typo3.com .. _Table-of-Contents: Table of Contents ----------------- **EXT: SNMP 1** **Introduction 1** What does it do? 1 Screenshots 2 **Users manual 4** Plugin configuration reference (local settings) 4 **Administration 4** **Configuration 5** Extension configuration reference (global settings) 5 **Known problems 6** **To-Do list 6** **Changelog 6** .. _Introduction: Introduction ------------ .. _What-does-it-do: What does it do? ^^^^^^^^^^^^^^^^ The Simple Network Management Protocol (SNMP) is a widely used protocol for network management and for the monitoring of network devices and their functions. It is not necessarily limited to TCP/IP networks. This extension allows the user to read the values of specified SNMP objects and display the returned object values and corresponding timestamps on a TYPO3 frontend page. Multiple SNMP frontend plugins can be used within one TYPO3 site. A global configuration is used as basic setting for all entities, plugins can be configured individually using local settings. This extension requires a SNMP installation for PHP, see http://php.net/snmp for details. You should be familiar with SNMP to use this extension and to understand the configuration options. .. _Screenshots: Screenshots ^^^^^^^^^^^ |img-1| Fig. 1:Example page with multiple SNMP plugins |img-2| Fig. 2: SNMP plugin used for a water temperature sensor in production environment |img-3| Fig. 3: Local settings for plugin (inserted as content element into a page) |img-4| Fig. 4: Global extension settings in TYPO3's Constant Editor .. _Users-manual: Users manual ------------ Before using the frontend plugin, the SNMP extension has to be installed and the global configuration has to be set in Constant Editor (see “Administration”/”Configuration”). After having this done, integrate the plugin into your TYPO3 page as a content element by choosing the plugin “SNMP object value display”. When editing the content element, you can configure local settings individually for each frontend plugin used in your site (see “Screenshots” Fig.3 and reference table below). Some of these settings will overwrite the global extension settings from Constant Editor for individual usage of multiple SNMP plugins. .. _Plugin-configuration-reference-local-settings: Plugin configuration reference (local settings) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. ### BEGIN~OF~TABLE ### .. _tx-ptsnmp-object-id: tx\_ptsnmp\_object\_id """""""""""""""""""""" .. container:: table-row Property tx\_ptsnmp\_object\_id Data type string Description **SNMP Object ID** : An absolute OID beginning with "." replaces the global OID from Constant Editor, a relative OID (beginning with a digit) is appended to the global OID from Constant Editor. .. _tx-ptsnmp-read-community: tx\_ptsnmp\_read\_community """"""""""""""""""""""""""" .. container:: table-row Property tx\_ptsnmp\_read\_community Data type string Description **SNMP read community** : Local setting for SNMP read community string. If set, this setting replaces the global setting from Constant Editor for the appropriate plugin. .. _tx-ptsnmp-hostname: tx\_ptsnmp\_hostname """""""""""""""""""" .. container:: table-row Property tx\_ptsnmp\_hostname Data type string Description **SNMP agent hostname** : Local setting for the SNMP agent hostname, e.g. IP address of the host. If set, this setting replaces the global setting from Constant Editor for the appropriate plugin. .. _tx-ptsnmp-value-type: tx\_ptsnmp\_value\_type """"""""""""""""""""""" .. container:: table-row Property tx\_ptsnmp\_value\_type Data type string [options] Description **SNMP object data type and display format** :: Local setting for data type and display format of the object value. If set to anything other than an empty string, this setting replaces the global setting from Constant Editor for the appropriate plugin. Possible values: "": use global setting, do not replace “str\_trim”: String: trimmed (whitespace stripped at beginning and end) “str\_orig”: String: unmodified (original format retained) ”int\_orig”: Integer: unmodified (original format retained) ”int\_fp1”: Integer: fixed-point: 1 decimal digit ”int\_fp2”: Integer: fixed-point: 2 decimal places ”int\_fp3”: Integer: fixed-point: 3 decimal places ”int\_fp4”: Integer: fixed-point: 4 decimal places ”int\_fp5”: Integer: fixed-point: 5 decimal places ”int\_fp6”: Integer: fixed-point: 6 decimal places .. _tx-ptsnmp-error-value: tx\_ptsnmp\_error\_value """""""""""""""""""""""" .. container:: table-row Property tx\_ptsnmp\_error\_value Data type string Description **Optional error value for the chosen data type** : If set, this value will be replaced by the “Error replacement string” configured in the global extension settings in Constant Editor. .. _tx-ptsnmp-caching-time: tx\_ptsnmp\_caching\_time """"""""""""""""""""""""" .. container:: table-row Property tx\_ptsnmp\_caching\_time Data type integer Description **Seconds to cache result** : Local setting for the time (noted in seconds) to serve the last cached result before sending a new SNMP request to the server (higher values help to keep down server load). If set, this setting replaces the global setting from Constant Editor for the appropriate plugin. .. _tx-ptsnmp-prefix: tx\_ptsnmp\_prefix """""""""""""""""" .. container:: table-row Property tx\_ptsnmp\_prefix Data type string Description **Object value display prefix** : Local setting for optional text to be placed left hand of the value display, e.g. object identifier. Use the HTML entity “ ” for a blank at the beginning or end of this string. If set, this setting replaces the global setting from Constant Editor for the appropriate plugin. .. _tx-ptsnmp-suffix: tx\_ptsnmp\_suffix """""""""""""""""" .. container:: table-row Property tx\_ptsnmp\_suffix Data type string Description **Object value display suffix** : Local setting for optional text to be placed right hand of the value display, e.g. unit. Use the HTML entity “ ” for a blank at the beginning or end of this string. Local settings of each plugin may overwrite this global value. If set, this setting replaces the global setting from Constant Editor for the appropriate plugin. .. ###### END~OF~TABLE ###### .. _Administration: Administration -------------- This extension requires: - a SNMP installation for PHP, see http://php.net/snmp for details - TYPO3 version 3.6.0 or above After checking these requirements, just install the extension and configure the global settings in Constant Editor (see ”Configuration”). .. _Configuration: Configuration ------------- After installing the extension, you have to configure the global extension settings in your template's Constant Editor at “pt\_snmp” (see “Screenshots” Fig. 4 and reference table below). These global extension settings are used for all SNMP frontend plugins used in your website, unless they are locally overwritten at individual plugin configuration. Overwriting global settings locally is limited to some special settings (see “User's manual”/”Plugin configuration reference (local settings)”). If you encounterproblems getting the extension to work, enable the debug mode (at the appropriate option at the end of Constant Editor's extension setting list) to print out details what the extension does. This is only for testing purposes, so be sure to disable the option in production environment! .. _Extension-configuration-reference-global-settings: Extension configuration reference (global settings) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. ### BEGIN~OF~TABLE ### .. _globalSnmpOid: globalSnmpOid """"""""""""" .. container:: table-row Property globalSnmpOid Data type string Description **SNMP Object ID** : Global value for SNMP OID (Notice: absolute OIDs should begin with "."). Local settings of each plugin may overwrite this global absolute value or append relative OIDs to it. Default .1.3.6.1.2.1 .. _globalSnmpReadCommunity: globalSnmpReadCommunity """"""""""""""""""""""" .. container:: table-row Property globalSnmpReadCommunity Data type string Description **SNMP read community** : Global value for SNMP read community string. Local settings of each plugin may overwrite this global value. Default public .. _globalSnmpHostname: globalSnmpHostname """""""""""""""""" .. container:: table-row Property globalSnmpHostname Data type string Description **SNMP hostname** : Global value for SNMP agent, e.g. IP address of the host. Local settings of each plugin may overwrite this global value. Default .. _globalValueType: globalValueType """"""""""""""" .. container:: table-row Property globalValueType Data type string [options] Description **Data type and display format** : Global setting for data type and display format of the object value. Local settings of each plugin may overwrite this global value. Possible values: “str\_trim”: String: trimmed (whitespace stripped at beginning and end) “str\_orig”: String: unmodified (original format retained) ”int\_orig”: Integer: unmodified (original format retained) ”int\_fp1”: Integer: fixed-point: 1 decimal digit ”int\_fp2”: Integer: fixed-point: 2 decimal places ”int\_fp3”: Integer: fixed-point: 3 decimal places ”int\_fp4”: Integer: fixed-point: 4 decimal places ”int\_fp5”: Integer: fixed-point: 5 decimal places ”int\_fp6”: Integer: fixed-point: 6 decimal places Default str\_trim .. _globalCachingTime: globalCachingTime """"""""""""""""" .. container:: table-row Property globalCachingTime Data type integer [int+] Description **Result caching time (seconds)** : Global setting for the time (noted in seconds) to serve the last cached result before sending a new SNMP request to the server (higher values help to keep down server load). Local settings of each plugin may overwrite this global value. Default 60 .. _globalValuePrefix: globalValuePrefix """"""""""""""""" .. container:: table-row Property globalValuePrefix Data type string Description **Object value display prefix** : Global setting for optional text to be placed left hand of the value display, e.g. object identifier. Use the HTML entity “ ” for a blank at the beginning or end of this string. Local settings of each plugin may overwrite this global value. Default .. _globalValueSuffix: globalValueSuffix """"""""""""""""" .. container:: table-row Property globalValueSuffix Data type string Description **Object value display suffix** : Global setting for optional text to be placed right hand of the value display, e.g. unit. Use the HTML entity “ ” for a blank at the beginning or end of this string. Local settings of each plugin may overwrite this global value. Default .. _globalErrorValueReplacement: globalErrorValueReplacement """"""""""""""""""""""""""" .. container:: table-row Property globalErrorValueReplacement Data type string Description **Error value replacement** : Replacement string for an returned error value (used if this is configured in local settings of the plugin) or for an empty return of the SNMP request (if not configured to use old cached values, see below). Default ----- .. _globalUseCacheOnEmptyValue: globalUseCacheOnEmptyValue """""""""""""""""""""""""" .. container:: table-row Property globalUseCacheOnEmptyValue Data type boolean Description **Use cache on empty value** : If checked, the plugin uses old cached values from the database if the SNMP request returns no value/an empty value. Not checked (as it is by default) means the plugin will show the error value replacement string (see above) in this case. Default 0 .. _globalEnableTimestampDisplay: globalEnableTimestampDisplay """""""""""""""""""""""""""" .. container:: table-row Property globalEnableTimestampDisplay Data type boolean Description **Enable timestamp display** : If checked (as it is by default), the timestamp of the currently displayed value is displayed additionally. To format the timestamp display use the options below. Default 1 .. _globalTimestampFormat: globalTimestampFormat """"""""""""""""""""" .. container:: table-row Property globalTimestampFormat Data type string Description **Timestamp display format** : Format of the displayed value's timestamp. Use the syntax of the 'format' parameter string of PHP's date() - see http://www.php.net/manual/en/function.date.php for details. (This setting has no effect if 'Enable timestamp display' is not checked.) Default d.m.Y, H:i:s .. _globalTimestampPrefix: globalTimestampPrefix """"""""""""""""""""" .. container:: table-row Property globalTimestampPrefix Data type string Description **Timestamp display prefix** : Global setting for optional text to be placed left hand of the timestamp display. Use the appropriate HTML entity for a blank at the beginning or end of this string. (This setting has no effect if 'Enable timestamp display' is not checked.) Default value from:  .. _boxPaddingValue: boxPaddingValue """"""""""""""" .. container:: table-row Property boxPaddingValue Data type integer[0-20] Description **Value display box padding** : Enter pixel size for padding of the value display table cell. Default 8 .. _boxPaddingTimestamp: boxPaddingTimestamp """"""""""""""""""" .. container:: table-row Property boxPaddingTimestamp Data type integer[0-20] Description **Timestamp display box padding** : Enter pixel size for padding of the timestamp display table cell. (This setting has no effect if 'Enable timestamp display' is not checked.) Default 3 .. _fontStyleValue: fontStyleValue """""""""""""" .. container:: table-row Property fontStyleValue Data type string Description **Value font CSS style** : The font format of the value display, noted in CSS styles. Default font-size:25px; font-weight:bold; color:black; text-align:center; font-family:Arial,Helvetica,Verdana,sans-serif; .. _fontStyleTimestamp: fontStyleTimestamp """""""""""""""""" .. container:: table-row Property fontStyleTimestamp Data type string Description **Timestamp font CSS style** : The font format of the value's timestamp display, noted in CSS styles. (This setting has no effect if 'Enable timestamp display' is not checked.) Default font-size:11px; font-weight:normal; color:#666666; text-align:center; font-family:Arial,Helvetica,Verdana,sans-serif; .. _bgColorValue: bgColorValue """""""""""" .. container:: table-row Property bgColorValue Data type string [color] Description **Value display background color** : Use colors as used in CSS (e.g. names like "blue" or RGB hex values like "#0000ff"). Default #ffff99 .. _bgColorTimestamp: bgColorTimestamp """""""""""""""" .. container:: table-row Property bgColorTimestamp Data type string [color] Description **Timestamp display background color** : Use colors as used in CSS (e.g. names like "blue" or RGB hex values like "#0000ff"). (This setting has no effect if 'Enable timestamp display' is not checked.) Default #dddddd .. _debug: debug """"" .. container:: table-row Property debug Data type boolean Description **Enable debug mode** : Outputs some debugging information for problem analysis and testing purposes. Do not enable in production environment. Default 0 .. _snmpWalk: snmpWalk """""""" .. container:: table-row Property snmpWalk Data type boolean Description **Enable SNMP walk** : Runs snmpwalk() and snmpwalkoid() on the object and prints all SNMP information received for testing purposes. Do not enable in production environment. snmpwalk() fetches all the SNMP objects from an agent, and snmpwalkoid() queries for a tree of information about a network entity. Both use a NULL object\_id here to read from the root of the SNMP objects tree. Default 0 .. ###### END~OF~TABLE ###### [plugin.tx\_ptsnmp\_pi1] .. _Known-problems: Known problems -------------- TYPO3 SQL Bug for MySQL 4.1: if you're using MySQL 4.1+ you'll encounter SQL problems (Install tool/Extension Manager). Edit the file “ext\_tables.sql” in your extension directory (ext/pt\_snmp) and remove the string “DEFAULT '0' NOT NULL “ from line 21 (the auto\_increment field). This is not done by default since it may lead to problems using TYPO3 in combination with former versions of MySQL. .. _To-Do-list: To-Do list ---------- - add a configurable formula option to affect the retrieved object value - add configurable garbage collection for old cache database records - send automatic system mails to site admin if database errors occur - maybe implement snmpset() options .. _Changelog: Changelog --------- - v1.0.0:- added configurable timestamp display for currently displayed SNMP object value- changed default global extension settings and CSS display formatting options- snmpwalk uses NULL object\_id now to read from the root of the SNMP objects tree- reorganization of the extension code, improved TYPO3 integration/CGL compliance, usage of DBAL functions- manual added- changed extension state to 'stable' after successful faultless use in production environment - v0.1.0: Translations added: Finnish and German. - v0.0.2: Initial version uploaded to TER |img-5| EXT: SNMP - 6 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. :border: 0 .. :id: Grafik3 .. :name: Grafik3 .. :width: 100% .. |img-2| image:: img-2.png .. :align: left .. :border: 0 .. :id: Grafik2 .. :name: Grafik2 .. :width: 100% .. |img-3| image:: img-3.png .. :align: left .. :border: 0 .. :id: Grafik4 .. :name: Grafik4 .. :width: 100% .. |img-4| image:: img-4.png .. :align: left .. :border: 0 .. :height: 486 .. :id: Grafik1 .. :name: Grafik1 .. :width: 547 .. |img-5| image:: img-5.png .. :align: left .. :border: 0 .. :height: 32 .. :id: Graphic1 .. :name: Graphic1 .. :width: 102