
pgsnmpd
=======
pgsnmpd is an SNMP agent that can return hierarchical information about the current 
state of Advanced Server.  pgsnmpd is distributed with and installed by the 
Postgres Plus Advanced Server Linux installer.  The pgsnmpd agent can operate 
as a stand-alone SNMP agent, as a pass-through sub-agent or as an AgentX sub-agent. 

After installing Postgres Plus Advanced Server, you will need to update the 
LD_LIBRARY_PATH variable.  Use the command:

    $export LD_LIBRARY_PATH=/opt/PostgresPlus/9.3AS/lib:$LD_LIBRARY_PATH

This command does not persistently alter the value of LD_LIBRARY_PATH; consult the 
documentation for your distribution of Linux for information about persistently 
setting the value of LD_LIBRARY_PATH. 

The examples in this document demonstrate the simplest usage of pgsnmpd, 
implementing read only access.  pgsnmpd is based on the net-snmp library; net-snmp 
is a complete SNMP framework that provides many features. For more information about 
net-snmp, please visit: 

    http://net-snmp.sourceforge.net


Configuring pgsnmpd
-------------------
The main configuration file for pgsnmpd is snmpd.conf.  A considerable number of 
directives can be specified in the configuration file. Please view the snmpd.conf 
man page for information about the available options (man snmpd.conf).

You can create the configuration file by hand, or can create the file with the snmpconf 
perl script, distributed with net-snmp package.  net-snmp is an open-source package 
available from:

    www.net-snmp.org  

To use the snmpconf configuration file wizard, download and install net-snmp.  Open a 
command line and enter:

    snmpconf  

When the configuration file wizard opens, it may prompt you to read in an existing 
configuration file.  Enter none to generate a new configuration file (not based on 
a previously existing configuration file).  

Then, select menu item 1: snmpd.conf to start the configuration wizard.  

snmpconf is a menu-driven wizard.  Choose from top-level menu selections to 
describe the different aspects of the snmp configuration file.  The top-level menu
includes:

    1: Access Control Setup
    2: Extending the Agent
    3: Monitor Various Aspects of the Running Host
    4: Agent Operating Mode
    5: System Information Setup
    6: Trap Destinations

As you specify each item from the top-level menu, snmpconf walks through a series 
of questions, prompting you for information required to build the snmp 
configuration file.  When you have specified information in all of the categories 
that are relevant to your system, enter <finished> to generate a configuration file. 

snmpconf creates a configuration file named snmpd.conf.  Copy the file to:

    /opt/PostgresPlus/9.3AS/share


Setting the Listener address
----------------------------
By default, pgsnmpd listens on port 161.  If the listener port is already being used 
by another service, you may receive the following error:
    
    Error opening specified endpoint "udp:161".

You can specify an alternate listener port by adding the following line to your 
snmpd.conf file:

    agentaddress $host_address:2000

The example instructs pgsnmpd to listen on UDP port 2000, where $host_address is 
the IP address of the server (e.g. 127.0.0.1). 


Invoking pgsnmpd
-----------------
Ensure that an instance of Advanced Server is up and running (pgsnmpd will connect 
to this server).  Open a command line and assume super-user privileges, before invoking 
pgsnmpd with a command that takes the following form:

    <INSTALLATION_LOCATION>/bin/pgsnmpd -b -c /opt/PostgresPlus/9.3AS/share/snmpd.conf 
     -C "user=enterprisedb dbname=edb password=edb_user_password port=5444"  

  Include the -b option to specify that pgsnmpd should run in the background.
  
  Include the -c option, specifying the path and name of the pgsnmpd configuration file.

  Include connection information for your installation of Advanced Server (in the form 
  of a libpq connection string) after the -C option.


Viewing pgsnmpd Help
--------------------
Include the --help option when invoking pgsnmpd to view other pgsnmpd command line 
options:

    pgsnmpd --help
  
  Version PGSQL-SNMP-Ver1.0
  usage: pgsnmpd [-s] [-b] [-c FILE ] [-x address ] [-g] [-C "Connect String"]
     -s : run as AgentX sub-agent of an existing snmpd process
     -b : run in the background
     -c : configuration file name 
     -g : use syslog
     -C : libpq connection string
     -x : address:port of a network interface
     -V : display version strings


Requesting information from pgsnmpd
-----------------------------------
You can query the pgsnmpd service with net-snmp client utilities.  For example:

    snmpgetnext  -v 2c -c public localhost .1.3.6.1.4.1.5432.1.4.2.1.1.0

In the example shown, 

  The "-v 2c" option instructs the snmpgetnext client to send the request in SNMP   
  version 2c format. 

  "-c public" specifies the community name. 

  "localhost" indicates the host machine running the pgsnmpd server. 

  ".1.3.6.1.4.1.5432.1.4.2.1.1.0" is the identity of the requested object (in this 
  case, a database name).

  To see a list of all databases, increment the last digit by one (e.g. .1.1, .
  1.2, .1.3 etc.)

The encodings required to query any given object are defined in the MIB (Management 
Information Base).  An SNMP client can monitor a variety of servers; the information exposed by 
a given server is determined by the server type. Each SNMP server describes the exposed 
data in the form of a MIB (Management information base).

By default, pgsnmpd searches for MIB's in the following locations:

    /usr/share/snmp/mibs
    $HOME/.snmp/mibs


