
# --------------------------- ADD -------------------------------------------

<Add>
Add

Usage:  click \"Add;\" complete dialog; click \"Add.\"

You can manually add a server by providing the following information to 
CandleDBConfig:

1) Server name - the name of the database server you want to monitor.

2) Home directory - the fully-qualified name of the directory in which the server 
   was installed.

3) $Product version -  the version or release level of the database executable.

4) Init file name - the fully-qualified name of the database initialization file. 
   This field is optional and is provided for information purposes only.  The OMA
   for $Product does not require an init file name.

5) Login ID - the database login ID used to connect with $Product.

6) Password - the password to use with \"Login ID.\"

Once this information has been provided, the list of database servers shown in 
CandleDBConfig is updated to include the new server.

</Add>

# --------------------------- CHANGES ---------------------------------------
#
# Removed since it was only current to 98R2.

# --------------------------- DISPLAY ---------------------------------------
#
# DISPLAY has been combined with MODIFY.


# --------------------------- EXCLUDE ---------------------------------------

<Exclude/Include>
Exclude/Include

Usage:  select one or more database servers from those displayed in 
CandleDBConfig; click \"Exclude.\"

\"Exclude\" is actually a toggle.  Use it to exclude servers that you do not 
want to monitor.  If a server is currently excluded, then \"Exclude\" will 
re-activate and include it with those servers you are monitoring.
 
If your \"Search\" also finds non-running servers, CandleDBConfig considers any
valid $init_name file that points to a real database to represent a server.
However, an $init_name file may be experimental or obsolete.  \"Exclude\" allows
you to exclude these servers from further consideration. 

Note, it is NOT necessary to exclude a server just because the server is not
running.  You can configure an agent to monitor a non-running server and even
start that agent.  The agent will register with the CMS and will periodically
try to connect with the database.  If the database is started, the agent will
begin reporting on it.  Thus, you could define an agent to monitor a part-time
$Product database, and that agent would report database activity as it occurs.

The \"Status\" field of the database servers shown in CandleDBConfig is updated 
to show excluded servers.

</Exclude/Include>

# --------------------------- INTRO   ---------------------------------------
#
# Not used.

# --------------------------- LIST ------------------------------------------

<List Config Files>
List Config Files

Usage:  select one or more database servers from those displayed in 
CandleDBConfig; click \"List;\" view configuration file; if displayed, use the 
\"Prev\" and \"Next\" buttons to view different config files; click \"Cancel.\"

\"List\" is used to view the contents of the databse server configuration files 
created by CandleDBConfig.  At this time, the files can only be viewed; they
cannot be edited from CandleDBConfig.

</List Config Files>

# --------------------------- LOCATE ----------------------------------------

<Search II (Disk Searches)>
Search II (Disk Searches)

Usage:  click \"Search II;\" select a search type; click \"Go.\"

\"Search II\" provides several search techniques that you can use if \"Search\" 
did not find all of the databases you want to monitor.  Your \"Search II\" choices
are:

1) Search scripts in \$PATH, looking for $home_name.

   If you normally use locally-written scripts to start database applications,
   each script must contain a statement that sets $home_name to the database's
   installation directory.   This option searches all scripts in your UNIX
   \$PATH looking for such a statement.

2) Search, starting at a specific directory.  This directory is usually the \$HOME 
   of the database owner.  However, you can specify any directory provided a 
   full pathname is used.  This option is similar to 1) except that the search is
   constrained to directories under the specified directory instead of those 
   given in \$PATH.
   
3) Search for possible owners of $Product.

   You can request that CandleDBConfig search through the disk files under the
   \$HOME directories of UNIX users that may own the database installation.  A
   list is then displayed of all UNIX users who have the characters \"$Prd\" or
   \"dba\" in either their ID or description and thus, might be $Product owners.
   After you select users from this list, CandleDBConfig searches through their 
   directory trees looking for $Product installations.  

   Note, this option supports users that are defined in your /etc/passwd file or 
   your \"yp\" or \"nis\" shared login databases.  Notice too that file systems
   are given in the list.  This field helps you determine whether to consider a 
   user since it tells you where the user's disk is physically located.

   Caution:  searches through NFS file systems can take a very long time if the
   file system is managed by a machine on the other end of a slow communication
   link.  However, such file systems do not usually contain database servers that 
   run on this machine.


The list of database servers shown in CandleDBConfig is then updated to include 
any additional servers found using the \"Search II\" techniques.

</Search II (Disk Searches)>

# --------------------------- LOGIN  ----------------------------------------

<Specify Logins/Passwords>
Specify Logins/Passwords

Usage:  select one or more database servers from those displayed in 
CandleDBConfig; click \"Specify;\" complete dialog; click \"OK.\"

\"Specify\" allows you to define the database logins and passwords that the agent
uses to access the database.  You are free to select any new or existing database
login ID.   The default login is "candle".  Note, database ID's are defined by 
the database administrator and allow access to the database.  A UNIX login ID is 
not necessarily a database login ID, but the two can have the same name.  Servers
which are defined to the OMA for $Product but which do not have any login or
password information are shown with an (I) for incomplete in CandleDBConfig.

\"Specify\" ONLY tells the Candle monitoring agents how to connect to the database.
CandleDBConfig does not create the database login ID, assign it a password or
grant the necessary authorities.  It is your responsibility to ensure that the 
database login and password match the ones you specify here.  However, \"Verify\"
will check that the login/password specified in CandleDBConfig actually works 
for your database.

If you leave the password field emtpy, CandleDBConfig asks whether you really 
want a null password.  A null password means the database login was configured 
to work without a password.  For security, the password appears as \"xxxxxx\" in 
the log file, $CANDLEHOME/logs/<host_name>_dd_config.log  

Note for Oracle 7.1.4:  Oracle 7.1.4 only allows the internal administration 
login ID \"sys\" to read the performance views.  This is a bug which Oracle fixed
in later releases, but no fix is available for 7.1.4.  Thus, when connecting to
an Oracle 7.1.4 database, you must specify a database login ID of \"sys\".  

The list of database servers shown in CandleDBConfig is then updated to show any 
new login ID's. 

</Specify Logins/Passwords>

# --------------------------- MODIFY  ---------------------------------------

<Modify/Display>
Modify/Display

Usage:  select one or more database servers from those displayed in 
CandleDBConfig; click \"Modify;\" enter or change values in dialog; click
\"Modify.\"

\"Modify\" lists all of the following configured attributes for a server and 
allows you to change any of them except the server name: 

1) Home directory - the fully-qualified name of the directory in which the server 
   was installed.

2) $Product version - the version or release level of the database executable.

3) Init file name - the fully-qualified name of the database initialization file. 
   This field is optional and is provided for information purposes only.  The OMA
   for $Product does not require an init file name.

   IMPORTANT:  if a server has changed names, DO NOT use this field to point to
   the new $init_name file.  Instead, exclude this server, and let CandleDBConfig 
   add the new name as a new server.   

4) Login ID - the database login ID used to connect with $Product.

5) Password - the password to use with \"Login ID.\"

The list of database servers shown in CandleDBConfig is then updated to show any 
new configuration information.

</Modify/Display>

# --------------------------- OPTIONS ------------------------------------------

<Options>
Options

Usage:  click \"Options;\" select options; click \"OK.\"

\"Options\" is used to set the runtime behavior of CandleDBConfig operations.
If \"verfiy configuration files\" is selected, every CandleDBConfig operation
will ensure that the database config files, located in $CANDLEHOME/config, have 
the correct format.  

By default (\"use existing log file\") CandleDBConfig writes an entry to its 
existing log file, $CANDLEHOME/logs/<host_name>_dd_config.log, each time it 
performs an operation.  If you want to log only the latest operation or nothing
at all, then select either \"create new log file\" or \"do not write to log file.\"

</Options>

# --------------------------- OWNER  ----------------------------------------
#
# OWNER is now a part of Search2.

# --------------------------- SCAN ------------------------------------------

<Search>
Search

Usage:  if desired, check \"not-running;\" click \"Options;\" select options;
click \"OK;\" click \"Search.\"

When you invoke CandleDBConfig or press \"Search,\" CandleDBConfig performs an
initial scan of your environment to look for all running $Product servers.  If
you check \"not running,\" then CandleDBConfig will also search databases that
are not currently running.  The results of a search are displayed in the
CandleDBConfig dialog.
 
CandleDBConfig examines all running $Product servers, locates where they are
installed on your UNIX system and acquires other information about them.  The
time needed to complete a search depends on what version of UNIX you are running.

If you requested that CandleDBConfig search for non-running servers, it will
create an internal list of all potential $home_name directories and look for any
server defined there.  CandleDBConfig develops this list of potential $home_name 
directories from:

1) The $home_name directory of any running server(s).

2) The current setting of the $home_name environmental variable, if any.

3) Any statement in an automatic script (.profile, .login, etc.) in the database
   owner's \$HOME directory that creates the $home_name environmental variable.

4) If the Oracle post-installation root script, \$ORACLE_HOME/orainst/root.sh,
   was run when Oracle was installed, then it created a registry file named 
   /etc/oratab.  Both Oracle and Candle recommend that you run this script so 
   your Oracle servers can be easily found.  Note, CandleDBConfig assumes that 
   the registry or oratab file is named /etc/oratab.

If \"Search\" finds a server that you do not wish to monitor, you can exclude
it using the \"Exclude\" button.  In addition, any search options chosen with the 
\"Options\" button are in effect until you change them.

</Search>

# --------------------------- SYSTEM ---------------------------------------

<System/DB Config>
System/DB Config

The following is a brief overview of the system and database preparation needed
before the OMEGAMON Monitoring Agent (OMA) can monitor a database.  Consult the
document \"Installing Candle Products on UNIX\" for complete details. 

SYSTEM

1) The kddos executable requires special UNIX permissions.  These permissions
   should have been set when the OMA was installed.  If not, they can be set
   using the Candle product installer.  Refer to the \"Installing Candle Products 
   on UNIX\" document for details.

2) The CMS must be seeded with the appropriate seed data.  The CMS should have
   been seeded when the OMA was installed.  If not, the CMS can be seeded using
   the Candle product installer.  Refer to the \"Installing Candle Products on
   UNIX\" document for details.

DATABASE

INFORMIX
   
The only authorization needed for Informix is the right to connect to the 
database.  $CANDLEHOME/misc/koxgrant.sql has the correct SQL syntax to do this.

The OMA for Informix includes a program which needs to run as the optional
Informix ALARMPROGRAM.  Modify the ONCONFIG so that ALARMPROGRAM is
$CANDLEHOME/<arch>/koxerr for your kind of UNIX system.  If you already have a
custom ALARMPROGRAM, then modify the ONCONFIG ALARMPROGRAM statement to point
to koxerr.sh, and modify koxerr.sh to refer to your program.  The koxerr.sh
script has complete instructions.

ORACLE

The OMA for Oracle uses an Oracle login ID to connect to the database.  Except 
for Oracle 7.1.4, the OMA may use any Oracle ID, even an ID that is used for 
other purposes.  CandleDBConfig does not create this ID.  The ID may be defined 
without a password if you wish.  If so, indicate a null password to CandleDBConfig. 
In addition, Oracle logins and passwords are NOT case-sensitive.

The following Oracle SQL statement defines an ID and password to Oracle.  In 
this example, \"oralogin\" indicates the Oracle login you will use and \"password\"
its password:

  CREATE USER oralogin IDENTIFIED BY password;

Security requirements differ for these Oracle releases:

  7.1.4  The OMA for Oracle must connect as \"sys.\"  This is an Oracle limitation.

  7.1.6  You may use any Oracle login, but it must have authority to read any
         table.  If the ID is \"candle,\" you would grant this authority by
         connecting to Oracle with an Oracle login that has DBA priviledges and
         issuing the following SQL statement:

           GRANT SELECT ANY TABLE TO oralogin;

         This requirement is an Oracle limitation.

  7.2 and later.  You may use any Oracle login, but it requires only specific 
      privileges granted to it.  Candle supplies an SQL script which performs 
      these grants.  This script is located in $CANDLEHOME/misc/korgrant.sql.
      Here are brief instructions for running this script.  Consult the 
      \"Installing Candle Products on UNIX\" document for more details.

      a) Set the Oracle environmental variables, ORACLE_SID and ORACLE_HOME, for 
         this installation.  If you have completed the configuration for the 
         databases, you can \"source\" the files in the config directory to set 
         these variables.

      b) Start sqlplus.

      c) Issue the following at the SQL prompt:  SQL> @korgrant candle

      Caution:  sqldba and svrmgr(l) do not allow parameters with sql scripts.  
      If you run korgrant.sql with one of these programs, you must modify it to 
      replace all occurences of &1 with the logon id you wish to use.

The OMA for Oracle requires that the Oracle performance views and synonyms be
installed.  These are created by the Oracle installer if it is run to completion.  
The performance views and synonyms can also be created by the appropriate SQL 
script in ORACLE_HOME/rdbms/admin.  Consult your Oracle documentation for details.
Note, this requirement is not necessary if you use the Oracle \"sys\" login ID, 
which you must do for Oracle 7.1.4.

In Oracle 7.2 only, Oracle ignores grants to the V\$LATCH table.  To correct 
this, apply Oracle patch to correct \"base bug #254661.\"  This patch enables you 
to view data in the \"Cache Totals Report.\"  If you do not install this patch, 
you must install Oracle with the \"sys\" login.

The OMA for Oracle does not require access to the SYS.DBA_VIEWS and 
SYS.DBA_SYNONYMS tables, but the \"Verify\" procedure of CandleDBConfig does.  If 
CandleDBConfig cannot read these tables, it cannot fully verify the installation.
However, the OMA will still work.

SYBASE

The OMA for Sybase uses a Sybase login ID to connect to the database.  It may
use any Sybase ID, even an ID that is used for other purposes.  CandleDBConfig 
does not create this ID.  The ID may be defined without a password if you wish.  
If so, indicate a null password to CandleDBConfig.  In addition, Sybase logins 
and passwords ARE case-sensitive.

The following Sybase isql statement defines an ID and password to Sybase.  In 
this example, \"syblogin\" indicates the Sybase login you will use and \"password\" 
its password:    

  sp_addlogin syblogin,password
  go

Candle also supplies an SQL script, $CANDLEHOME/misc/koygrant.sql, to grant the 
necessary authorities.

The OMEGAMON Monitoring Agent for Sybase uses the Sybase \"Open Client\" library 
to connect to Sybase.  If \"Open Client\" is not installed on your Sybase system, 
the agent cannot connect to Sybase, and you will receive a message in the 
col.out file that says CT-INIT failed.   You can determine whether \"Open Client\" 
is installed by checking under your Sybase home directory for lib/libct.a.

If \"Open Client\" is not installed, you must obtain either of the following:

1) the \"Open Client\" product from Sybase.  It is our understanding that each
   Sybase server license entitles the customer to a single free \"Open Client\"
   license.  Contact Sybase for more information.

2) a runtime version of CTlib for Sybase.  This is available, free of charge,
   from Candle Level 2 support.  Candle has Sybase's permission to distribute
   the runtime portion of CTlib.

</System/DB Config>

# --------------------------- VERIFY ---------------------------------------

<Verify OMA Installation>
Verify OMA Installation

Usage:  click \"Verify;" check results show in dialog; click \"Cancel.\"

\"Verify\" ensures that an OMA was installed correctly by checking that:

1) there is a valid UNIX version.

2) UNIX permissions are correct on key directories under $CANDLEHOME.

3) special UNIX permissions are set for kddos.

4) the product configuration files exist for this host.

For each configured server, \"Verify\" checks that:

5) the configuration file is valid and the configuration is complete.

6) the database home directory and database initialization file exist and that 
   you have read permission on the file.

7) the Sybase Open Client product is installed for the server.

8) the database server is running.  If not, verification of the OMA for this 
   database cannot continue.

9) you can successfully login to the database.

10) you can access Oracle V\$ performance tables.  If you cannot, it could be 
    that:

    a) the tables were never created (See chapter 5 of the planning guide,
       section entitled: \"V\$ Dynamic Performance Tables.\").

    b) the korgrant.sql script was not run.

    Without DBA authority, it is impossible to know which.

    Note, \"Verify\" tests all Oracle performance views and synonyms.  OMA for 
    Oracle has failed at some sites because the performance views and synonyms 
    were only partially created at Oracle installation.  Also, this test requires
    that the Oracle user have SELECT authority to SYS.DBA_VIEWS and
    SYS.DBA_SYNONYMS.  These grants are NOT part of the korgrant.sql script
    because most Oracle installations grant SELECT to catalog tables to PUBLIC.

11) you can access the Oracle 7.2 SYS.V_\$LATCH performance view.  If you cannot, 
    refer to the \"Installing Candle Products on UNIX\" document.

12) the Sybase koygrant.sql script has been run.  This script grants the sa_role
    to your Sybase login.  

13) for Informix, your site has made the necessary modifications to the ONCONFIG 
    file ALARMPROGRAM statement.  See the \"Installing Candle Products on UNIX\" 
    document.

14) the CMS host responds to a ping.

15) the agent can connect to a CMS.  If it cannot, it could be that:

    a) the CMS Host, CMS port number or CMS name is wrong.

    b) the CMS is not running.

    Without direct access to the CMS machine and knowledge of exactly where the
    CMS is installed on that machine, CandleDBConfig cannot tell which.

16) the CMS has been seeded and recycled since seeding.  If the CMS was just 
    recycled, the early results can be inconclusive.  For this reason, \"Verify\"
    lets the agent run for up to five minutes before concluding that the CMS is 
    down or unseeded.  However, if the agent determines that the CMS is down, the 
    IVP agent is recycled immediately because the default behavior is to wait ten 
    minutes before trying to reconnect.
 
\"Verify\" does not check that:

1) the cat, atr, sql (seed data) and his files at the CMS are at a consistent 
   level with this installed agent. 

2) timing problems cause communication timeouts.

3) for Informix, your site has not revoked SELECT authority for the system tables 
   from PUBLIC.  The koxgrant.sql script does not contain specific grants for 
   these - it is assumed that your site has left these grants as Informix 
   originally shipped them.

</Verify OMA Installation>

