Install and Configure the APM Database

The APM Database stores data from Introscope and CA CEM. You deploy the APM database on either PostgreSQL or Oracle. To install the APM Database, you must be a Local Administrator (Windows). Review the following before installing the APM database:
apmdevops106
The APM Database stores data from Introscope and CA CEM. You deploy the APM database on either PostgreSQL or Oracle. To install the APM Database, you must be a Local Administrator (Windows). Review the following before installing the APM database:
2
2
Prepare for APM Database Installation
This section discusses the steps to prepare the servers, finalize target directory for installation, database selection considerations, and verify the schema version of the APM database.
Follow these steps:
  1. APM Database Location
  2. Database Selection Considerations
  3. Create the APM Database Schema Manually
  4. Run Individual SQL Scripts to Manage the APM Database Schema
  5. Verify the Schema Version of the APM Database
APM Database Location
You can install the APM database in the following locations:
  • On the same computer as the Enterprise Manager.
  • On a computer that the Enterprise Manager can access over a network.
You can install the APM database independently of the Enterprise Manager or other components. For example, you may want to install the database schema on a separate, dedicated database server. Or you may want to prepare the database schema in the planning phase before you set up the Enterprise Manager connection to it.
The APM database is often hosted on a separate server, so it is common to use the Database Only installation option once. When you install other components, use the existing schema option to connect to that APM database.
To install the APM database schema for PostgreSQL:
  • You can create a database instance or you can specify an existing database instance directly from the Enterprise Manager installer.
  • You can also create the database administrator account and APM database owner during the installation process.
To install the APM database schema for Oracle:
  • The Oracle database instance must exist.
  • At least one Oracle database user account must exist that you can use to connect to the database instance.
Database Selection Considerations
Determine the type of database that you want to use. Consider the following information:
  • You do not have a database instance installed:
    The Enterprise Manager installer installs the PostgreSQL database automatically. You cannot use the installer to create an Oracle database instance.
  • You want to minimize the database maintenance and keep the configuration of your environment simple:
    The PostgreSQL database is an easier alternative to an Oracle database. The PostgreSQL database requires minimal configuration and ongoing management.
  • You are managing the APM database without the support of a database administrator group:
    The PostgreSQL database typically does not require a separate database administrator to install or maintain the data integrity and user access. The Enterprise Manager runs periodic maintenance scripts on the APM database.
  • Your organization has a database for a specific vendor:
    You may be required to use that database.
Create the APM Database Schema Manually
In some environments, it may be desirable or necessary to create the APM database schema manually. For example, your database administrator may not want to run the Enterprise Manager installer interactively or use a response file. The administrator may want to manually control the tables, views, and sequences added to the database while ensuring no other components are installed on the database server. Instead, the database administrator can manually create the database schema, and can use the scripts that are installed by default in the
<EM_Home>
/install/database-scripts
directory.
Follow these steps:
  1. Open a command or terminal window as appropriate for your operating environment.
  2. Navigate to the
    <EM_Home>/install/database-scripts
    directory for your operating environment. For example, if you are creating the APM database schema on a Linux or Solaris computer, navigate to the
    <EM_Home>/install/database-scripts/unix
    directory:
    cd <EM_Home>/install/database-scripts/unix
  3. Run the
    createschema.bat
    or
    createschema.sh
    command appropriate for your operating environment using the following arguments:
    CreateSchema -databaseName <database_name> -databaseType <database_type> -host <host_name> -port <port_number> -releaseVersion <version> -scriptsDir <directory> -user <user_name> -password <password>
    • databaseName
      Specifies the database name or service identifier of the database instance. For example, if you are creating an Oracle database schema, set this parameter to the Database Service Name .
    • databaseType
      Specifies whether the database is an Oracle database or a PostgreSQL database. For example, if you are creating an Oracle database schema, set this parameter to oracle. The only valid values are oracle and postgres. If you are running the command on Linux or UNIX, keep in mind that this setting is case-sensitive.
    • host
      Specifies the host name or IP address of the computer that hosts the database server.
    • port
      Specifies the port number for communication between the Enterprise Manager and the APM database. For example, the default port for the LISTENER port on an Oracle database is 1521. The default port for the PostgreSQL database is 5432.
    • releaseVersion
      Specifies the version of the APM database schema to create. For the current version of the APM database schema, you should set this option to the current version.
    • scriptsDir
      Specifies the directory for database-specific SQL scripts. For example, you should use
      <EM_Home>/install/oracle/database-scripts
      if you are creating an Oracle database schema or
      <EM_Home>/install/database-scripts
      if you are creating a PostgreSQL database.
    • user
      Specifies the user name for connecting to the database and creating the APM database schema. If you are creating an Oracle database schema, the user name you specify is the database owner.
    • password
      Specifies the password for the specified database user name.
    For example, run a command similar to the following script to manually create the APM database schema for Oracle on a Linux computer:
    ./createschema.sh -databaseName cemdb -databaseType oracle -host localhost -port 1521 -releaseVersion <Current_Version> -scriptsDir /home/Introscope<VersionNumber>/install/oracle/database-scripts -user apmadmin -password quality
    The CreateSchema program calls several individual SQL scripts to remove any existing APM database schema objects and create new APM database tables, constraints, indexes, procedures, views, and sequences.
    For example, run a command similar to the following script to manually create the APM database schema for PostgresSQL on windows:
    createSchema.bat -databaseName cemdb -databaseType postgres -host localhost -port 5432 -releaseVersion <Current_Version> -scriptsDir "C:\Program Files\CA APM\Introscope<VersionNumber>\install\database-scripts" -user apmadmin -password quality
  4. Check the
    schematools.log
    file in the install directory. Verify that the schema is created successfully or troubleshoot problems with the schema creation. The directory and file are created automatically in the directory from which you started the CreateSchema command. For example, if you are creating the APM database schema on a Linux or Solaris computer, navigate to the
    <EM_Home>/install
    directory.
Run Individual SQL Scripts to Manage the APM Database Schema
In most cases, you can use wrapper programs, such as the
CreateSchema
or
dbdrop
programs, to create or remove APM database schema objects in an Oracle environment. These programs call individual SQL scripts to perform specific operations, such as creating tables and views or adding constraints. You can use these individual scripts independent of the wrapper programs for greater flexibility in managing the APM database schema. For example, if you already have a repository of scripts and processes in place for managing different schemas and databases, you may want to add the scripts for managing APM database objects to your current repository and management processes.
To upgrade the APM database on Oracle to a minor or patch release, run the database upgrade script.
The individual SQL scripts for managing APM database schema objects are installed by default in the
<EM_Home>/install/oracle/database-scripts
directory.
You can execute the individual SQL scripts in the following order to
DROP
an existing schema:
<EM_Home>/install/oracle/database-scripts/dropprocedures-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/dropsequences-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/dropsequences-apm-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/dropviews-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/droptables-apm-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/droptables-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/dropquartz-1.5.1-oracle-<VERSION>.sql
If you run the above scripts without using the dropdb.sh or dropdb.bat file, also empty the Recycle Bin for the Oracle APM user after running the above scripts.
You can execute the individual SQL scripts in the following order to
CREATE
a new Oracle schema:
<EM_Home>/install/oracle/database-scripts/createtables-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/createsequences-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/addindexes-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/addconstraints-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/addviews-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/procedures-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/defaults-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/initdb-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/create-apm-tables-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/create-apm-sequences-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/add-apm-indexes-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/add-apm-constraints-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/apm-procedures-oracle-<VERSION>.sql <EM_Home>/install/oracle/database-scripts/quartz-1.5.1-oracle.sql
To run the individual SQL scripts to create the APM database schema manually:
  1. Open a command or terminal window as appropriate for your operating environment.
  2. Navigate to the
    <EM_Home>/install/oracle/database-scripts
    directory. For example:
    cd <EM_Home>/install/oracle/database-scripts
  3. Start SQL *Plus from the command line or using Oracle Enterprise Manager, and connect to the database instance, if needed.
  4. Execute the individual SQL scripts in the following order to create a new Oracle schema for the APM database:
    createtables-oracle-<VERSION>.sql createsequences-oracle-<VERSION>.sql addindexes-oracle-<VERSION>.sql addconstraints-oracle-<VERSION>.sql addviews-oracle-<VERSION>.sql procedures-oracle-<VERSION>.sql defaults-oracle-<VERSION>.sql initdb-oracle-<VERSION>.sql create-apm-tables-oracle-<VERSION>.sql create-apm-sequences-oracle-<VERSION>.sql add-apm-indexes-oracle-<VERSION>.sql add-apm-constraints-oracle-<VERSION>.sql apm-procedures-oracle-<VERSION>.sql quartz-1.5.1-oracle.sql
    For example, execute the script to create APM database schema tables:
    start createtables-oracle<VERSION>.0
    To upgrade the database to a minor or patch release, run the database upgrade script.
    For more information about starting SQL *Plus or executing SQL scripts, see the Oracle documentation for the version of the Oracle database you are using.
Verify the Schema Version of the APM Database
Verify that an APM database has the correct schema version.
Follow these steps:
  1. Use a tool such as pgAdmin or psql for PostgreSQL or isql or SQL*Plus for Oracle.
  2. Run the following SQL statement:
    SELECT ts_db_versions FROM ts_domains
    The SQL statement returns a value representing the version of the APM database schema you have installed.
Install the APM Database
You install the APM database using one of the following options:
Install a PostgreSQL APM Database
The APM database stores data from CA Introscope; and CA CEM. Review system information before you install the PostgreSQL APM database.
Follow these steps:
  1. APM Database on PostgreSQL User Accounts
  2. PostgreSQL User Accounts on Windows
  3. PostgreSQL User Accounts on Linux and Solaris
  4. Install the PostgreSQL APM Database
  5. Configure PostgreSQL on Linux
  6. Configure PostgreSQL on Solaris
  7. Create the APM Database
  8. Create APM Database Schema Manually on PostgresSQL
  9. Upgrade the APM Database Schema
  10. Troubleshoot the PostgreSQL Installation
APM Database on PostgreSQL User Accounts
When first installing the APM database on PostgreSQL, the following user accounts affect the PostgreSQL database:
  • PostgreSQL administrator user
    -- The default is postgres. This account is the database owner and database administrator.
  • APM database user
    -- The default is admin. Although the name is "admin," it is not the database administrator user account.
  • Operating system user account that runs the PostgreSQL service
    -- The default is postgres. In many cases, the installer creates this user so that the user account can run the PostgreSQL service. This service enables the database to run.
PostgreSQL User Accounts on Windows
Consider the following information about the Windows user accounts for PostgreSQL and the Introscope installer:
  • The installer creates the operating system user account with the same name as the PostgreSQL Admin account name. You can change the names of any of the PostgreSQL-related user accounts on Windows during installation. For example, if you change the default name of the PostgreSQL admin user from “postgres” to “PostgresAdmin,” the installer creates the Windows user account as “PostgresAdmin.”
  • The installer creates the operating system user account with the same password as the PostgreSQL admin user.
  • To install the APM database on PostgreSQL, run the installer as an Administrator account.
  • To install Introscope only, run the installer as any Windows user that has permissions to install programs.
  • To run the Enterprise Manager as a service, the installing user account must have permissions to do so.
PostgreSQL User Accounts on Linux and Solaris
Consider the following information about the Linux and Solaris user accounts for PostgreSQL and the Introscope installer:
  • If you run the installer as root, the installer creates the “postgres” operating system account.
  • If you run the installer as a non-root account, the installer does not create the “postgres” operating system user.
  • During installation as root user, you cannot change the name of the “postgres” operating system user account. If desired, you can change the name of the database user from the default (admin). We recommended that you keep the name of the PostgreSQL administrator the same as the operating system user account that runs the PostgreSQL service.
  • The installer creates the “postgres” account without a password.
  • If installing Introscope only, you can run the installer as any user account that has permissions to install programs.
You can run the Introscope installer as the root user or a non-root user. The installer does
not
recognize sudoer access. The installer installs Introscope under the user account that you are logged in as when running the installer.
  • When running the installer as root and installing the APM database on PostgreSQL, the installer installs PostgreSQL under the "postgres" user. The "postgres" user can already exist.
    The root user owns the entire install directory for installations that were installed as root. You can change the ownership of the directory structure to your administrator user account, so that you can update configurations, and so forth. Use the chown command to change the ownership of the directory structure. This behavior is a reason why we recommend that you install the APM database separately from the Enterprise Manager.
  • When running the Introscope installer as a non-root account and installing the APM database on PostgreSQL, the installer installs PostgreSQL under that same non-root account.
Install the PostgreSQL APM Database
You must install the shared library file
libreadline.so.6
 on Solaris 10 to install the database. If such library is not installed the database cannot be started.
Do not run antivirus software on the APM database server. Antivirus software can reduce the database performance.
Use the Enterprise Manager installer to install an Enterprise Manager, WebView, and the APM database.
Follow these steps:
  1. Locate and launch the appropriate installer for your environment.
    The installer guides you through the installation.
  2. Accept the terms of the CA End User License Agreement (EULA).
    Specify the installation path and directory using ASCII characters only. Non-ASCII characters, such as Japanese, are not supported for PostgreSQL installation.
    The Choose Install Set window opens.
  3. Select the type of installation and click Next.
    • Complete Installation
      Installs or upgrades the Enterprise Manager, WebView, and the APM database.
    • Minimal Installation
      Installs or upgrades only the Enterprise Manager and the APM database.
    • Database Only
      Installs or upgrades only the APM database.
    • AO Platform Integration Only
      Integrates an existing Installation of CA APM with an existing AO platform. You can also select this option, to integrate the AO Platform as a stand-alone component of an existing CA APM instance.
      See the Integrate with AO Platform page for detailed procedure to integrate your CA APM and CA AO Platform.
    • Custom Installation
      Select the individual components to install or upgrade.
    If you selected Custom installation, the Choose Product Components window opens.
  4. Select the product components that you want to install, and click Next.
    If you do not select the APM database, the installer prompts you to specify connection information when installing the Enterprise Manager. Specifying the connection information verifies that the Enterprise Manager can connect to an existing APM database.
  5. In the Choose Install Folder, click Next to accept the default installation directory, or click Browse to specify a different location.
    Default directories for Enterprise Manager installation:
    • Windows:
      C:\Program Files\CA APM\Introscope<
      version
      >
    • UNIX:
      /opt/PostgreSQL-<version>
    • For SAP:
      • On Windows:
        C:\usr\sap\ccms\apmintroscope\
      • On UNIX:
        /usr/sap/ccms/apmintroscope/
    Warning!
    Verify that the path does not include a leading space. A leading space causes the installer to interpret the path as relative, not absolute.
    If you are using an installer that includes a bundled JVM, the Configure JVM Settings window opens.
    If you are installing the Enterprise Manager and the APM database separately, do not use the same installation directory for both components. For example, install the Enterprise Manager to the default directory and specify a different directory for the APM database. Using the same directory for both components can cause the installer to overwrite uninstall data that is required to uninstall the Enterprise Manager.
  6. (Optional) Select Yes to configure JVM settings during the installation. Select No to accept the defaults, or if you plan to configure them manually later.
    If you select Yes, a JVM Settings window opens for each Introscope component during the installation.
  7. Click Next.
    You can install an Enterprise Manager of Managers (MOM) or a Collector. You can create a database instance directly from the installer.
  8. When prompted to select the APM database, select Postgres.
  9. Follow the prompts to install the database.
    • Install database
      Installs a new PostgreSQL database instance and APM database schema.
  10. Specify the directory name for the APM database. Click Next.
    The default APM database installation directories are:
    • Windows:
      <
      EM_Home>\database
    • UNIX:
      /opt/database
    Use a separate, dedicated disk or I/O subsystem for APM database data to avoid affecting Enterprise Manager performance. See CA APM Sizing and Performance
    for sizing information.
    Warning!
    On Linux, if you change the database installation directory, do not change it to be under the /root directory. If you do so, PostgreSQL installs but fails to start. PostgreSQL limits the installation location from the /root directory.
  11. Specify the port number and administrative account information for the PostgreSQL database instance. Click Next.
    • Database Connection Port
      Specifies the port that the Enterprise Managers use to communicate with the APM database. The default is 5432.
    • PostgreSQL Administrator Username
      Specifies the PostgreSQL administrator user account that has administrative privileges for the PostgreSQL database. The default account name is postgres.
    • PostgreSQL Administrator Password
      Specifies the password for the PostgreSQL administrator user account. The password must adhere to your password security policies.
      • The installer creates a user account with the same name as the PostgreSQL Administration user name.
      • If a user account with this name already exists, the installation continues if the specified password matches the existing user account password. If the passwords do not match, the installation fails.
      • The installer uses the PostgreSQL Administrator user to create the operating system user account, the postgres service user account, and the PostgreSQL superuser account.
      After the installer completes, you can change the postgres account password and the PostgreSQL superuser password.
    The installer verifies the connection information at the
    end
    of the installation process. Review the installation log files for more information.
    The PostgreSQL Service User window opens.
  12. Click OK to accept the password. You can click Re-Enter Database Admin Settings to change the password.
  13. Specify the following information for the APM database schema. Click Next.
    • Database Name
      Specifies the name of the APM database schema. The default schema name is cemdb.
      If you are upgrading a database schema, use the name of the database schema you are upgrading.
    • Database User
      Specifies the database user name you want associated with the APM database schema. The database user name cannot contain uppercase or special characters.
    • Password
      Specifies the password for the database user that is associated with the APM database schema.
      See Support Knowledge Document 12881: How to change the password of the APM Database User on Postgres after installation.
    If the existing database schema is a version that is invalid to upgrade, the installer provides the options to create a schema or to continue.
  14. Review your settings in the Database Configuration Summary. Click Install.
    The installer notifies you when installation is complete.
    If errors occur during the installation, the installer directs you to view the appropriate component log files. For assistance, contact
    CA Support
    .
Configure PostgreSQL on Linux
If you have installed PostgreSQL on Linux using a non-root user account, as a system administrator you perform configuration tasks.
If you use your own script to start the PostgreSQL service, you do not need to configure the PostgreSQL startup scripts to run after restart.
Follow these steps:
  1. Configure the
    <
    InstallationDir
    >/install/database-install/linux/postgresql-<version>
    startup script to run automatically after restart.
  2. Copy the
    postgresql-<version>
    script to the init.d folder and then run the following command:
    chkconfig - add postgresql-<version>
  3. Set levels 2,3,4,5 to on.
More Information:
For more information see the KB article 16381: How can we tune Postgres database for Linux box with 16GB Memory?
Configure PostgreSQL on Solaris
If you have installed PostgreSQL on Solaris using a non-root user account, as a system administrator you perform configuration tasks.
If you use your own script to start the PostgreSQL service, you do not need to configure the PostgreSQL startup scripts to run after restart.
Follow these steps:
  1. Browse to the following PostgreSQL startup scripts:
    <APM_Db_Home>/postgresql.xml <APM_Db_Home>/postgresql
  2. Copy the PostgreSQL startup scripts to the following correct locations so that they run automatically after restart.
    Solaris 10 example:
    /var/svc/manifest/application/database/postgresql.xml /lib/svc/method/postgresql
    Solaris 11 example:
    /lib/svc/manifest/application/database/postgresql.xml
  3. Add services using the svcadmn feature in Solaris 10 or 11.
    If the installation failed with a shared memory error, set the shared memory value higher.
Create the APM Database
Create the APM database from the pgAdmin interface, or manually after you install PostgresSQL on the Enterprise Manager server.
Create the APM Database in pgAdmin
Use the pgAdmin interface to create the APM database.
Follow these steps:
  1. Open the pgAdmin interface.
  2. Right-click the local host, and select Connect.
  3. Enter the Postgres service user password and click OK.
    A Database node is added to the tree view in the Object Browser pane.
  4. Right-click the Database node, and provide the database name and owner.
    The APM database is created.
Create the APM Database Manually
Create the APM database manually from command window after you install the PostgresSQL on the Enterprise Manager server.
Follow these steps:
  1. Open a command window.
  2. Navigate to the
    <EM_Home>/install/database-scripts
    directory.
  3. Run the
    createdb-postgres.bat
    command, and provide the following parameter values:
    Createdb-postgres.bat [dbserverhost] [dbinstalldir] [dbserviceuser] [dbservicepwd] [dbname] [dbuser] [dbpassword] [dbport <optional>]
    • dbserverhost
      Specifies the host name or IP address of the computer that hosts the database server.
    • Dbinstalldir
      Specifies the directory where the database is installed.
    • Dbserviceuser
      Specifies the user name for the Postgres service.
    • Dbservicepwd
      Specifies the user password for the Postgres service.
    • Dbname
      Specifies the database name.
    • Dbuser
      Specifies the database user name.
    • Dbpassword
      Specifies the password for the specified database user name.
    • (Optional) Dbport
      Specifies the port number for communication between the Enterprise Manager and the PostgresSQL APM database. The default port for the PostgreSQL database is 5432.
Create APM Database Schema Manually on PostgresSQL
After you create the PostgresSQL database, create the APM database schema on the database server. The createSchema.bat command lets you create a schema until the latest CA APM releases.
Follow these steps:
  1. Open a command prompt window.
  2. Navigate to the
    <EM_Home>/install/database-scripts
    directory.
  3. Run the
    createSchema.bat
    command using the following parameters:
    CreateSchema.bat databaseType, databaseName, host, port, user, password, desiredVersion, scriptsDir, is64bit
    • databaseName
      Specifies the database name.
    • databaseType
      Specifies the PostgresSQL database.
    • host
      Specifies the host name or IP address of the computer that hosts the database server.
    • port
      Specifies the port number.
    • user
      Specifies the database user name.
    • password
      Specifies the password for the specified database user name.
    • desiredVersion
      Specifies the version for upgrading to a desired release.
    • scriptsDir
      Specifies the directory where the database is installed.
    • is64bit
      Specifies whether the platform is 32-bit or 64-bit.
Upgrade the APM Database Schema
Upgrade the APM database schema from the last CA APM major release to the current release of CA APM.
Follow these steps:
  1. Open a command prompt window.
  2. Navigate to the
    <EM_Home>/install/database-scripts
    directory.
  3. Run the
    upgradeSchema.bat
    command using the following parameters:
    UpgradeSchema.bat [-connections <connections>] -databaseName <name> -databaseType <dbtype> -desiredVersion <toVersion> -host <name/ip> -is64bit <is64bit> -password <pwd> -port <port>
    [-postgresInstalldir <postgresInstalldir>] -scriptsDir <dir> -user <name>
    • connections
      Specifies the maximum number of simultaneous database connections.
    • databaseName
      Specifies a given name for database or service ID.
    • databaseType
      Specifies the Postgres database.
    • desiredVersion
      Specifies the CA APM version for upgrading to a desired release.
    • Host
      Specifies the name or IP address of the database hostname.
    • is64bit
      Specifies whether the platform is 32-bit or 64-bit.
    • password
      Specifies the database password.
    • port
      Specifies the database port.
Start or Stop the APM Database on PostgreSQL
If the PostgreSQL service stopped or did not start automatically after you restarted the computer, you can start the PostgreSQL service manually.
(Linux  and Solaris only)
Start and Stop the APM Database
Use one of the following commands:
  • Navigate to the directory that contains the PostgreSQL startup script for your operating system:
    <APM_Db_Home>/bin/pg_ctl
  • Run the following start command:
    pg_ctl -D <APM_Db_Home>/data -l <APM_Db_Home>/data/pg_log/postmaster.log start
  • To stop the database, run the following command:
    pg_ctl -D <APM_Db_Home>/data stop
    (Linux only) If you installed PostgreSQL with APM as the root user, you can use system service tool to start and stop the database. Use
    service postgresql-<version> start
    to start it and use
    service postgresql-<version> stop
    to stop the database.
(Windows only) Follow these steps:
  • Select Control Panel, Administrative Tools, Services.
  • Start (or stop) pgsql-
    <version>
    - PostgreSQL Server
    <version>.
Troubleshoot the PostgreSQL Installation
This section describes troubleshooting solutions, that you may face during the PostgreSQL Installation.
PostgreSQL Installation Error
Symptom:
After trying to install the APM database on PostgreSQL, I get the following error:
-INSTALL_POSTGRES_STDERR=/root/Introscope9.0.0.0/install/database-install/linux/install-postgres.sh\: line 87\: ed\: command not found\n
Solution:
Set the path to editor "ed". (The editor is generally located under /bin. For example, for bash shell: export PATH=$ PATH:/bin.)
Troubleshoot the PostgreSQL Installation on Solaris
Symptom:
The non-root installation of PostgreSQL on Solaris failed due to insufficient shared memory.
Solution:
Have your Solaris system administrator run the following command:
projadd -U postgres -K "project.max-shm-memory=(priv,7000MB,deny)" user.postgres
Symptom:
When installing a new PostgreSQL database instance for the APM database on Solaris, the installer installs the instance. However, the installer fails to create the APM database schema.
Solution:
  • Check the memory and disk available on computer where you are running the installer.
  • If you have sufficient memory and disk space, check that the PostgreSQL database instance is installed and running.
  • Rerun the installer and select the option to connect to the existing database instance.
  • Select the option to install a new database schema.
    Performing these steps in two installer sessions should enable you to install the PostgreSQL database and the APM database schema on a Solaris system.
PostgreSQL Installation Problems
Symptom:
I am having problems installing the PostgreSQL database.
Solution:
Various factors can cause PostgreSQL installation problems, and the installer can detect many of them. However, because the installer cannot detect all installation problems, try some of the following suggestions.
Review the following log files for potential errors:
  • PostgreSQL database installation log file
    This file is located in %TEMP% on Windows and /tmp/ on Linux. The log filename is either install-postgresql.log or bitrock_installer_nnnnn.log.
  • PostgreSQL database server log file
    This file is located in
    <APM_Db_Home>
    /data/pg_log, and contains database run-time error messages.
  • Enterprise Manager installer variables file
    The Enterprise Manager installer saves all runtime variables in <
    EM_Home
    >/UninstallerData/base/installvariables.properties.
  • Database tools schema population log file
    This file is
    <
    EM_Home
    >/install/schematools.log
    . Use this file to see if there are any database schema population errors.
Many installation problems can be related to permissions. Check the PostgreSQL database installation file for these issues:
  • Database installation folder permission
    The installer needs permission to create the database directory. This permission is important when installing on Linux using a non-root account.
  • Database port is already used or (particularly on Linux) the port is closed and cannot connect to the database from another computer.
    Have your system administrator open the database port on the firewall.
  • Database administrator account permissions
    The installer needs the permission to create the database administrator account. If the account already exists, verify that you entered the correct password. The installer cannot validate the password. The password must be compliant with your password security policies.
  • Database lock file permission (UNIX only)
    If the lock file already exists and a user other than the one running the installer owns it, the PostgreSQL installation can fail. A typical lock file name is /tmp/.s.PGSQL.5432.lock.
  • Shared memory setting is properly configured (UNIX only)
    When running the installer as a non-root user, first configure the shared memory setting before you install the database.
  • Installer must be run by a user account with Administrator privileges and permission to create a service (Windows)
Other areas to verify:
  • The configuration that you are installing onto is supported.
  • PostgreSQL is not already installed on the computer. If you try to install a second PostgreSQL instance, errors occur about the port being in use, the service already registered, failed to access the lock file, and so forth.
  • Verify that if PostgreSQL was previously installed on the computer that it was successfully uninstalled. Even when an older version of PostgreSQL is installed (such as 8.3):
    1. Back up the database.
    2. Uninstall PostgreSQL.
    3. Install the new version of PostgreSQL.
    4. Restore the backup file into the new installation.
  • (Windows, All Versions) Verify that the
    <APM_Db_Home>
    \data\pg_hba.conf file has the IPv6 entry configured correctly.
  • If you use a non-root, non-postgres account to install PostgreSQL on Linux or Solaris, the database restore from PostgreSQL 8.3.x to the current version may not work because the database owner is different. Due to this, CA Technologies recommends that you use the non-root "postgres" user account to install the APM database.
  • The Enterprise Manager installer creates the PostgreSQL database with unicode encoding as UTF8 locale. If the system locale is set to C (SQL_ASCII) or (LATIN1), the create database script may fail. If the create db script fails because of the locale, set the system locale to UTF8 before installing the database. Another option is to set
    LC_ALL=C
    to
    LC_ALL=en_US.UTF-8
    in the shell and then install the database.
  • If you encounter an error about being unable to create the postgres service user, turn off any antivirus programs and re-run the installer.
  • If you encounter an error that says "the database cluster initialization failed", this may be because PostgreSQL was unable to change directory permissions. Open the <EM_Home>\database directory and manually set the permissions for the \data subdirectory. If the subdirectory \data does not exist, create. Then uninstall PostgreSQL and re-install. This error often happens on Windows 2008 or Vista machines where UAC is enabled.
  • When an error message indicates that a port is either used or closed, open that port on the firewall for the computer.
  • If you run the installer in silent mode and creating a PostgreSQL database schema fails, run the installer in GUI or console mode to create the schema.
Forgotten or Lost Password to the APM Database
Symptom:
I installed the APM database using PostgreSQL and I do not have the PostgreSQL password. I either lost or forgot the password.
Solution:
The following procedure applies to PostgreSQL installations.
Follow these steps:
  1. Open the pg_hba.conf file in your text editor.
    This file is in the
    <Postgres_Home>/data
    directory. For example, /opt/database/data.
  2. In the pg_hba.conf file, look for the line for the postgres user:
    local all all password
    or
    local all postgres md5
    Network users begin the line with "host" and also provide an IP address and netmask:
    host all postgres 10.255.255.10
    If your system is configured for all users to authenticate in the same way, you see "all" in place of a username:
    local all all md5
    The method may be set to "md5" or "password" or one of the other many options.
  3. Comment out the line that applies to either all users or the postgres user, and add the following line:
    local all postgres ident sameuser
    The above line allows you to connect as the postgres user without having to specify a password. Local is for UNIX domain socket connections only.
    local all postgres ident sameuser
    Copy the lines that you are changing and comment the original lines.
  4. Save your changes to the pg_hba.conf file.
  5. Restart the postgres service. You can find it here:
    /etc/rc.d/init.d/
  6. Run the following command:
    service postgresql-<version> restart
    Example:
    service postgresql-9.6 restart
  7. Run the following command to change to sudo access for the postgres user:
    su - postgres
    This allows you to run commands as the postgres user.
  8. Launch psql, the command-line client for PostgreSQL. You can find psql either in <Postgres_Home>/bin or <Postgres_Home>/pgAdmin3.
    ./psql
    This causes psql to open the PostgreSQL database. It should not prompt you for a password. This is what the login prompt looks like:
    psql (<version>) Type "help" for help. postgres=#
  9. From the psql command prompt, run the following psql command to change the database password:
    ALTER USER postgres WITH ENCRYPTED PASSWORD 'password';
    Psql lists the following text to indicate success:
    ALTER ROLE postgres=#
  10. Type
    \q
    and then press ENTER to exit psql.
  11. Re-open the pg_hba.conf file and set it back to the original settings. Use either md5 or password authentication, but md5 is more secure.
  12. Restart the postgres service again
  13. To test it, launch psql again. It should prompt you for the (reset) password.
Install an Oracle APM Database
The APM database stores data from CA Introscope; and CA CEM. Review system information before you install the Oracle APM database.
To install an Oracle APM database, as an administrator, follow these basic steps:
  1. Install the APM Database as Oracle Schema
  2. Configure the APM Database Schema Owner for Oracle
  3. Allow Segment Creation in Oracle
  4. Install the Database
Install the APM Database as Oracle Schema
You can install the APM database as an Oracle database schema.
The APM database schema does not require the Oracle database to have any specific configuration options except that its character set must be Unicode Transformation Format (UTF-8) compliant. The default character set is selected based on the locale of the operating system when the database is installed and supports only a single language. However, Oracle recommends using AL32UTF8 as the database character set even if your database only stores data in one language.
Although the AL32UTF8 character set is recommended, you can install the APM database schema on Oracle if you selected a different character set. Use the AL32UTF8 character set so that the database can support more than one language or multibyte characters.
Follow these steps:
  1. Install and configure an Oracle database instance.
  2. Identify the Oracle database instance that you want to use.
  3. Verify that the database server and database instance are running and available locally or over the network. The installer must be able to connect to the database to install the APM database schema.
Configure the APM Database Schema Owner for Oracle
In Oracle, a database schema is always associated with a specific database user. Several role-based user accounts are created automatically when you install an Oracle database. These built-in accounts are typically preconfigured with permissions to perform specific tasks. A best practice to create an Oracle database user account that is specifically for the APM database.
The APM database schema for Oracle requires an empty Oracle user namespace to exist on the Oracle database to which you plan to connect. A system identifier (SID) identifies the Oracle database instance.
Follow these steps:
  1. Create or identify a user account with access to the Oracle database instance.
    This user account becomes the owner of the APM database schema.
    For information about database users, see the Oracle documentation for the version of the Oracle database you are using. For example, for an Oracle 11g Enterprise Edition database, open the Enterprise Manager Database Console, select the Server page, and then click Users. You can add and configure a database user for the APM database schema. The CA APM Communities Message Board provides information about creating a user and APM database schema in Oracle.
  2. Grant the following privileges to the database owner user account:
    CONNECT RESOURCE CREATE TRIGGER CREATE SEQUENCE CREATE TYPE CREATE PROCEDURE CREATE TABLE CREATE SESSION CREATE VIEW ANALYZE
  3. Grant user accounts the Unlimited Tablespace permission.
  4. Verify that the user namespace does not have any tables, views, procedures, or other objects defined.
Allow Segment Creation in Oracle
Valid for: Oracle 11g Enterprise Edition, Release 2 (11.2.0.1.0) at a minimum
By default, Oracle does not allocate space for nonpartition tables when tables are created. Instead, the default Oracle configuration allocates space for the table when the first record is inserted. This default behavior prevents the APM database schema from being created successfully. To create the APM database schema, modify an Oracle database property to allow the immediate creation of database segments.
Follow these steps:
  1. Create or verify that the user account for the APM database owner exists.
  2. Allow space to be allocated to a table when the Create Table statement is executed.
  3. Run the following SQL statement:
    ALTER SYSTEM SET deferred_segment_creation=FALSE scope=both
    When the Create Table statement is executed, space can be allocated to a table.
For more information about the deferred segment creation, see the Oracle website.
Install the Database
You must already have an Oracle database instance to which you can connect. You must also already have an Oracle database user name and password that is the APM database owner.
Do not run antivirus software on the APM database server. Antivirus software can reduce the database performance.
Follow these steps:
  1. Locate and launch the appropriate installer for your environment.
    The installer guides you through the installation.
  2. Accept the terms of the CA End User License Agreement (EULA).
    If you are running the installer in console mode on Linux or Solaris, edit the ca-eula.txt file to accept the agreement and save the file. When the installer prompts you for the location, specify a relative or absolute location and filename.
    Specify the installation path and directory using ASCII characters only. Non-ASCII characters, such as Japanese, are not supported for PostgreSQL installation.
    The Choose Install Set window opens.
  3. Select the type of installation and click Next.
    • Complete Installation
      Installs or upgrades the Enterprise Manager, WebView, and the APM database.
    • Minimal Installation
      Installs or upgrades only the Enterprise Manager and the APM database.
    • Database Only
      Installs or upgrades only the APM database.
      For an existing Oracle database instance, this option validates the Enterprise Manager connection to the database using the specified credentials. If needed, the installer upgrades the APM database schema on Oracle.
    • AO Platform Integration Only
      Integrates an existing Installation of CA APM with an existing AO platform. You can also select this option, to integrate the AO Platform as a stand-alone component of an existing CA APM instance.
      See the Integrate with AO Platform page for detailed procedure to integrate your CA APM and CA AO Platform.
    • Custom
      Installation
      Select the individual components to install or upgrade.
    If you selected Custom, the Choose Product Components window opens.
  4. Select the product components that you want to install, and click Next.
    If you do not select the APM database, the installer prompts you to specify connection information when installing the Enterprise Manager. Specifying the connection information verifies that the Enterprise Manager can connect to an existing APM database.
  5. In the Choose Install Folder, click Next to accept the default installation directory, or click Browse to specify a different location.
    Default directories for Enterprise Manager installation:
    • Windows: C:\Program Files\CA APM\Introscope<
      version
      >\
    • UNIX: /root/Introscope<
      version
      >/
    • For SAP:
      • On Windows: C:\usr\sap\ccms\apmintroscope\
      • On UNIX: /usr/sap/ccms/apmintroscope/
    Warning!
    If you are installing on Linux and pasting in the path, verify that the path does not include a leading space. If the path has a leading space, the installer interprets the path as relative, not absolute.
    If you are using an installer that includes a bundled JVM, the Configure JVM Settings window opens.
    Note:
    If you are installing the Enterprise Manager and the APM database separately, do not use the same installation directory for both components. For example, install the Enterprise Manager to the default directory and specify a different directory for the APM database. Using the same directory for both components can cause the installer to overwrite uninstall data that is required to uninstall the Enterprise Manager.
  6. If desired, select Yes to configure JVM settings during the installation. Select No to accept the defaults, or if you plan to configure them manually later.
    If you select Yes, a JVM Settings window opens for each Introscope component during the installation.
  7. Click Next.
  8. When prompted to select the APM database, select Oracle.
  9. Specify the database instance appropriate for your environment:
    • Update schema or create new database schema
      Connects to an Oracle database and updates or adds the APM database schema to that database. In most cases, select this option unless you have previously run the installer using the Database Only installation option. The default is to update or create a schema.
    • Use existing schema
      Connects to an Oracle database that has the APM database schema installed. If you select this option, verify that an APM database exists.
  10. Specify the connection information for the installer to use to connect to the Oracle database where the APM database schema is installed.
    • Database Host
      Specifies the host name or IP address of the computer where the Oracle database instance is installed.
      To specify an IPv6 address, enter the address in brackets. For example, [0:0:0:0:0:FFFF:192.168.00.00].
    • Database Port
      Specifies the port number for the Enterprise Manager to use to communicate with the APM database. The default port is 1521, which is also the default port for the LISTENER service in Oracle databases.
    • Database SID Name
      Specifies the Oracle system identifier (SID) which is the unique name of the database instance. The database instance must exist for the connection to be successful.
    • Database Username
      Specifies the database user name that owns the APM database schema. This user must exist as a valid database user in the database instance specified.
    • Database Password
      Specifies the password for the database user that owns the APM database schema.
    The installer creates the APM database schema under the database user name you specify.
    If you are creating a schema, the user namespace you specify must be empty. If the installer detects any tables, views, or other database objects, an error message prompts you to enter a different user name.
  11. Review your settings in the Database Configuration Summary. Click Install.
    The installer notifies you when the installation is complete.
Post APM Database Installation Steps
Perform the following steps post installation of APM database to customize the databse or to update configuration of any existing database information.
Specify APM Database Settings After Installation
In most cases, you specify connection information for the APM database when you run the installer. However, you can also configure the connection to the APM database manually after the installation completes.
For example, if a remote server hosts the APM database and the server becomes unavailable. The attempt to connect fails. You can continue the installation and then configure the connection manually after completing the installation.
Follow these steps:
  1. Open the tess-db-cfg.xml file for editing. The file is located in the following directory, depending on your operating system:
    • Windows:
      <EM_home>
      \config\
    • UNIX:
      <EM_home>
      /config/
  2. For the hibernate.connection.url property, replace the current settings with the database hostname (or IP address), port, and database name.
    For example:
    <property name="hibernate.connection.url">jdbc:postgresql://127.0.0.1:5432/cemdb</property>
  3. For the hibernate.connection.username property, specify the database user name.
    This name is not the PostgreSQL administrator user name.
  4. For the hibernate.connection.password property, specify the database user password in plain text.
  5. For the plainTextPasswords property, change the setting to true. This property allows you to enter the password in plain text.
    When the Enterprise Manager starts, Introscope sets the plainTextPasswords property back to false and encrypts the password.
    APM uses the AES128 algorithm for encryption. Each installation has its own key so it is not possible to decrypt the encrypted string without access to the file system of the machine where the EM is installed.
(Optional) Enable SSL Support for PostgreSQL
When enabling SSL for Oracle database, you must consult your DBA and Oracle documentation for the implementation details.
CA APM supports encrypted connection between the APM Enterprise Manager and PostgreSQL database. SSL communication is supported on Windows and UNIX. You enable the communication between the Enterprise Manager and PostgreSQL.
You cannot enable SSL during installation. DB related tools such as Configuration import/export, Create schema, DB Backup, DB Restore, DB Upgrade, Drop Schema, Create DB, DB Migration, and Create Appmap schema for PostgreSQL are not supported.
Follow these steps:
To enable SSL on PostgreSQL server, follow these steps:
  1. Install OpenSSL on the computer.
  2. Generate self-signed certificate for the server using the following OpenSSL command:
    openssl req -config <OPEN_SSL_DIR>\bin\openssl.cnf -new -text -out server.req
  3. Generate the server key from the generated private key using the following command:
    openssl rsa -in privkey.pem -out server.key
  4. Generate the server certificate using the following command:
    openssl req -config <OPEN_SSL_DIR>\bin\openssl.cnf -x509 -in server.req -text -key server.key -out server.crt
  5. Copy
    server.crt
    and
    server.key
    to the
    <POSTGRES_INSTALL_DIR>\data
    directory.
  6. On UNIX, make the user "postgres" the owner of
    server.key
    file and change file attributes to 0600 as follows:
    chown postgres:postgres server.key chmod 0600 server.key
  7. In postgresql.conf enable SSL as uncommenting the following line:
    ssl=on ssl_key_file = 'server.key' ssl_cert_file = 'server.crt'
  8. Restart Postgres DB to load the new SSL configuration.
  9. Both unencrypted and SSL connections are enabled on PostgreSQL Server on the same port. The default port is 5432.
If you want PostgreSQL to accept only SSL connections from remote computers, also change host all all 0.0.0.0/0 password to hostssl all all 0.0.0.0/0 md5 and comment out host all all ::/0 password in the pg_hba.conf file.
To establish Java with SSL, follow these steps:
  1. Install CA APM with default settings.
  2. Generate the certificate for Java client on the server certificate using the following command:
    openssl x509 -in server.crt -out server.crt.der -outform der
    Run on the same computer where the server certificate/key was issued.
  3. Copy server.crt.der to the computer where CA APM is running.
  4. Go to
    <APM_INSTALL_DIR>\jre\bin
    and
    import server.crt.der
    into Java (keystore) on which CA APM is running using the following command:
    keytool -keystore <APM_INSTALL_DIR>\jre\lib\security\cacerts -alias apm_postgresql -import -file <DIR>\server.crt.der
  5. When prompted, enter the keystore password.
    Default:
    changeit
  6. To establish CA APM with SSL, in the "tess-db-cfg.xml" file, add
    ?ssl=true
    in the
    tess-db-cfg.xml
    file after the schema name. For example:
    <property name="hibernate.connection.url">jdbc:postgresql://localhost:5432/cemdb?ssl=true</property>
  7. Restart the Enterprise Manager.
  8. SSL Communication between APM Enterprise Manager and PostgreSQL is established.
(Optional) Move the APM Database to a Different Machine
Valid for: PostgreSQL databases only
In some cases, you move the APM database to a different computer for scalability reasons or as part of your unique upgrade path. The following overview instructions apply to APM databases that are either newly installed or have already been upgraded.
SSL communication is not supported for APM database schema changes.
Follow these steps:
  1. Export the database to a database backup file.
  2. On the new computer, run the Enterprise Manager installer to install a new APM database using the following options:
    1. For the Install Set, click Database Only.
    2. Choose an installation directory that is not the Enterprise Manager home directory.
    3. For the database type, select PostgreSQL.
    4. Select the Install database option.
    5. Specify the directory name to use for the APM database schema.
    6. Enter the port number, and the PostgreSQL administrator user name and password for the new database instance.
    7. Enter the new APM database name, a database user name, and a password.
  3. Populate the new, empty APM database with the contents of the backup file that you created in Step 1.
  4. Connect all existing Enterprise Managers to the new database location.