Jump to: navigation, search

Aperi/install

Revision as of 01:08, 7 August 2007 by Toddsing.us.ibm.com (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

1. Plan for the database repository

Use this section to determine what relational database to use as the database repository for Aperi. There are two relational databases available for use with Aperi:

   * Apache Derby is a relational database implemented entirely in Java and available under the Apache License, Version 2.0. Click here for more information. Apache Derby is included with the Aperi installation and can be installed using the Aperi Configurator. Click here for instructions on how to install it using the Aperi Configurator.
     Note about Apache Derby Security: Aperi Storage Manager does not currently implement all the security features in Derby for an enterprise-wide management application. Most notably, the Aperi Configurator does not configure any user authentication for the Derby RDBMS.This means that anyone will be able to connect to and use the installation of Derby that comes with Aperi.
     Skip to the next section if you plan to use Apache Derby as the database repository.
   * DB2 8 for Linux UNIX and Windows. Click here for more information about this relational database.
     Complete the steps in this section if you plan to use DB2 as the Aperi database repository.

Perform the following steps to download and set up DB2 for use with Aperi Storage Manager:

  1. Download DB2. You can download DB2 from here.
  2. Install DB2 using the default settings. Note the db2admin password that you choose during the installation.
  3. Continue to the next section Install the Aperi Storage Manager files.

2. Install Aperi Storage Manager files

Install the Aperi Storage Manager files on machines:

   * Whose storage you want to manage and monitor.
   * Where you want to run the Aperi Storage Manager's user interface
   * Where you want to run the server component. This machine must be able to communicate with the machines where you install the agents and user interface.

Perform the following steps to install the server, agent, or GUI on a machine:

  1. Locate the Aperi Storage Manager .zip file.
  2. Place the .zip file in the directory where you want to install the product.
  3. Use an unzipping tool to unzip the file.
  4. Download required components that are not distributed with the Aperi Storage Manager .zip file. There are two methods for downloading required third-party files:
         * Use Aperi's Installer
         * Manually download and install the required files.
     This step describes the files that you must download manually (you cannot use the installer script to do so). Perform the following steps to download these required files:
         * Download BIRT Runtime 2.1.2.
              1. Go to http://www.eclipse.org/downloads/download.php?file=/birt/downloads/drops/R-R1-2_1_2-200702271000/birt-runtime-2.1.2.zip.
              2. Save the download to disk.
              3. Unzip the contents of birt-runtime-2.1.2.zip to a local directory. Within that local directory the zip file automatically creates a directory called /birt-runtime-2_1_2 that contains all the BIRT runtime files and subdirectories. For example: c:\bin\downloads\birt-runtime-2_1_2\.
              4. Perform the following tasks on the files you unzipped in the previous step:
                     o Start a command prompt session.
                     o Type the following command that corresponds to the operating system of the machine where you are installing Aperi:
                           + Windows: copy [aperi_install_directory]\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\WEB-INF\web.xml c:\temp
                             For example: copy c:\Aperi\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\WEB-INF\web.xml c:\temp
                           + Linux: cp /[aperi_install_directory]/plugins/org.eclipse.aperi.reporting_5.0.0/web/birt-viewer/WEB-INF/web.xml .
                             For example: cp /opt/aperi/plugins/org.eclipse.aperi.reporting_5.0.0/web/birt-viewer/WEB-INF/web.xml .
                       Note: You can substitute a directory other than c:\temp if needed.
                     o Press Enter. This will copy Aperi's existing web.xml to a temporary directory (for example, Windows: c:\temp or Linux: . where "." represents the working directory where the command is issued) to enure that it is not overwritten during the next step.
                     o Type the following command that corresponds to the operating system of the machine where you are installing Aperi:
                           + Windows: xcopy /s /e /i /y [birt-runtime-2_1_2_unzip_directory]\WebViewerExample c:\[aperi_install_directory]\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer
                             For example: xcopy /s /e /i /y c:\birt-runtime-2_1_2\WebViewerExample C:\Aperi\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer
                           + Linux: cp -r -f [birt-runtime-2_1_2_unzip_directory]/WebViewerExample/* /opt/[aperi_install_directory]/plugins/org.eclipse.aperi.reporting_5.0.0/web/birt-viewer/
                             For example: cp -r -f birt-runtime-2_1_2/WebViewerExample/*
                             /opt/aperi/plugins/org.eclipse.aperi.reporting_5.0.0/web/birt-viewer/
                     o Press Enter. The subdirectores under [birt-runtime-2_1_2_unzip_directory]\WebViewerExample are copied to [aperi_install_directory]\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\.
                       After copying these directories, the resulting Aperi directory structure will appear as follows:
                           + [aperi_install_directory]\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\logs
                           + [aperi_install_directory]\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\report
                           + [aperi_install_directory]\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\scriptlib
                           + [aperi_install_directory]\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\webcontent
                           + [aperi_install_directory]\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\WEB-INF\lib
                           + [aperi_install_directory]\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\WEB-INF\platform
                     o Type the following command that corresponds to the operating system of the machine where you are installing Aperi:
                           + Windows: copy c:\temp\web.xml [aperi_install_directory]\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\WEB-INF\web.xml
                             For example: copy c:\temp\web.xml C:\Aperi\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\WEB-INF\web.xml
                             Note: If you used a directory other than c:\temp make sure to use that directory in the copy command.
                           + Linux: cp web.xml [aperi_install_directory]/plugins/org.eclipse.aperi.reporting_5.0.0 /web/birt-viewer/WEB-INF/web.xml
                             For example: cp web.xml [aperi_install_directory]/plugins/org.eclipse.aperi.reporting_5.0.0/web/birt-viewer/WEB-INF/web.xml
                     o Press Enter.
                     o Type Yes and press Enter if you are prompted to overwrite web.xml. The web.xml file that you copied to a temporary directory (for example, the Windows c:\temp directory or the current working directory under Linux) is copied back in to [aperi_install_directory]\Aperi\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\WEB-INF\.
         * Download JavaHelp 1.1.3.
              1. Go to http://java.sun.com/products/javahelp/download_binary.html.
              2. Click the Download button under the JavaHelp 1.1.3 (Zip) section.
              3. Click Accept License Agreement.
              4. Click the down arrow to download the javahelp-1_1_3.zip file.
              5. Unzip the contents of javahelp-1_1_3.zip.
              6. Locate the \jh1.1.3\javahelp\lib\jh.jar file in the directory where you unzipped javahelp-1_1_3.zip.
              7. Copy jh.jar to [aperi_install_dir]\plugins\javax.help_1.0.0
              8. Copy jh.jar to [aperi_install_dir]\rcpgui\plugins\javax.help_1.0.0
  5. Download additional third-party files. Depending on your environment, you can download these additional required files manually or use Aperi's Installer script to perform the download automatically. To determine what works best for your environment, consider the following:
         * Automatic download: Use the Aperi Installer script (in regular or easy mode) to automatically download these additional third-party files. 
         * Manual download: Download these additional third-party files manually if any of the following is true:
               o The install process cannot access the Internet (firewall, policy, no connectivity, etc).
           Download the following files if you do not plan to use the Installer to perform the automatic downloads:
         * Download Geronimo 1.1.
              1. Go to http://www.apache.org/dist/geronimo/1.1/geronimo-tomcat-j2ee-1.1.zip.
              2. Save the download (geronimo-tomcat-j2ee-1.1.zip) to a local directory (such as /geronimo-1.1).
              3. Unzip the contents of geronimo-tomcat-j2ee-1.1.zip.
              4. Copy geronimo-j2ee_1.4_spec-1.1.jar to [aperi_install_dir]\plugins\javax.j2ee_1.0.0.
              5. Copy geronimo-j2ee_1.4_spec-1.1.jar to [aperi_install_dir]\rcpgui\plugins\javax.j2ee_1.0.0.
                 geronimo-j2ee_1.4_spec-1.1.jar is located in the following subdirectory where you unzipped geronimo-tomcat-j2ee-1.1.zip: /[location where you unzipped geronimo-tomcat-j2ee-1.1.zip]/repository/org/apache/geronimo/specs/geronimo-j2ee_1.4_spec/1.1.
         * Download iText 1.3.
              1. Go to http://downloads.sourceforge.net/itext/itext-1.3.jar?modtime=1112806930&big_mirror=0.
              2. Save the download (itext-1.3.jar) to a local directory.
              3. Copy itext-1.3.jar to [aperi_install_dir]\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\WEB-INF\lib
         * Download org.mortbay.jaas 5.1.10.
              1. Go to http://repo1.maven.org/maven2/jetty/org.mortbay.jaas/5.1.10/org.mortbay.jaas-5.1.10.jar.
                 Note: If this link does not work in your web browser, go to http://repo1.maven.org/maven2/jetty/org.mortbay.jaas/5.1.10/, right-click org.mortbay.jaas-5.1.10.jar, select Save Target As..., save it to your local disk, and skip to step 3.
              2. Save the download (org.mortbay.jaas-5.1.10.jar) to disk.
              3. Rename the jar from org.mortbay.jaas-5.1.10.jar to org.mortbay.jaas.jar.
              4. Copy org.mortbay.jaas.jar to [aperi_install_dir]\plugins\org.eclipse.aperi.reporting.jaas_1.0.0.
         * Download javax.servlet.jsp_2.0.0.v200612120446.jar.
              1. Go to http://www.eclipse.org/downloads/download.php?file=/eclipse/equinox/drops/S-3.3M6-200703231616/javax.servlet.jsp_2.0.0.v200612120446.jar.
              2. Click the mirror link closest to you and save the file locally.
              3. Copy javax.servlet.jsp_2.0.0.v200612120446.jar to [aperi_install_dir]\plugins\.
         * Download org.apache.commons.el_1.0.0.v200704241052.jar.
              1. Go to http://www.eclipse.org/downloads/download.php?file=/eclipse/equinox/drops/S-3.3M7-200705031400/org.apache.commons.el_1.0.0.v200704241052.jar.
              2. Click the mirror link closest to you and save the file locally.
              3. Copy org.apache.commons.el_1.0.0.v200704241052.jar to [aperi_install_dir]\plugins\.
         * Download org.apache.jasper_5.5.17.v200701082340.jar.
              1. Go to http://europa-mirror1.eclipse.org/tools/orbit/downloads/drops/R200706192011/bundles/org.apache.jasper_5.5.17.v200706111724.jar.
              2. Save the file locally.
              3. If the file has a .zip extension, rename it to .jar
              4. Copy org.apache.jasper_5.5.17.v200701082340.jar to [aperi_install_dir]\plugins\.
  6. If you plan to use DB2 as the database repository, continue to the next step. If you plan to use Apache Derby as the database repository, continue to step 8.
  7. Copy the DB2 JDBC driver into the directory where you unzipped the Aperi Storage Manager files. To do this perform the following steps:
        1. Locate the DB2 JDBC driver that was installed during the DB2 installation. On Windows, check C:\Program Files\IBM\SQLLIB\Java. The filenames are db2jcc.jar and db2jcc_license_cu.jar.
        2. Copy the driver files to the following Aperi directories:
               * /plugins/org.eclipse.aperi.db_1.0.0
               * /rcpgui/plugins
        3. Go to /plugins/org.eclipse.aperi.db_1.0.0/MANIFEST.
        4. Delete MANIFEST.MF.
        5. Rename DB2-MANIFEST.MF to MANIFEST.MF.
  8. (optional) Complete this step if you intend to use the Aperi report viewer from behind a firewall or from a location that does not have an internet connection. Otherwise, continue to the Configure Aperi Storage Manager section for information about how to set up the components you want to run on the machine where you unzipped the Aperi files.
     A web-based report viewer is available as a perspective within the RCP framework or as a standalone application viewed through a web browser. The report viewer is based on BIRT, an open source Eclipse-based reporting system that provides you with the ability to generate a number of reports based on storage data collected by Aperi.
     If you intend to use the report viewer from behind a firewall or from a location with no access to the internet, you must modify the DTD (Document Type Definition) in the web.xml files of the two web applications that comprise the report server. Each web.xml file contains the following XML DOCTYPE declaration after the Aperi copyright statement:
     <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
     Perform the following steps to modify the DTDs in the web.xml files:
        1. Create a copy of the original web.xml files as distributed with Aperi. The web.xml files are located in the following directories:
               * [aperi_install_dir]\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\WEB-INF\web.xml
               * [aperi_install_dir]\plugins\org.eclipse.aperi.reporting_5.0.0\web\aperi-reports\WEB-INF\web.xml
           For example, create a copy of these files under different names in the same directories such as:
               * c:\aperi\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\WEB-INF\web.xml.orig
               * c:\aperi\plugins\org.eclipse.aperi.reporting_5.0.0\web\aperi-reports\WEB-INF\web.xml.orig
           This ensures that you have a copy of the original files for backup purposes.
        2. Start a web browser and go to http://java.sun.com/dtd/web-app_2_3.dtd.
        3. Save the source of this page to: [aperi_install_dir]\reporting\web-app_2_3.dtd. Make sure the name of the file you save locally is web-app_2_3.dtd.
           Note: You can also right-click the link http://java.sun.com/dtd/web-app_2_3.dtd and select the "save target as" option to save the file locally.
        4. Open the following web.xml files in a text editor:
               * [aperi_install_dir]\plugins\org.eclipse.aperi.reporting_5.0.0\web\birt-viewer\WEB-INF\web.xml
               * [aperi_install_dir]\plugins\org.eclipse.aperi.reporting_5.0.0\web\aperi-report\WEB-INF\web.xml
        5. Edit the DTDs in each web.xml file to point to the local web-app_2_3.dtd file that you saved previously as follows:
           Change the text "http://java.sun.com/dtd/web-app_2_3.dtd" that appears in each file's DTD to: "file:///[aperi_install_dir]/reporting/web-app_2_3.dtd"
           For example, the modified DTD for the web.xml files might appear as follows:
           <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "file:///C:/Aperi/reporting/web-app_2_3.dtd">
        6. Save both web.xml files with the updated DTD.
        7. Continue to the Configure Aperi Storage Manager section for information about how to set up the components you want to run on the machine where you unzipped the Aperi files.

4. Install Aperi Storage Manager

Use the Install tool to set up Aperi Storage Manager components on the machine where you unzipped the product. The package that you unzipped contains the run-time files for all of Aperi Storage Manager's main components: a host-based agent, a server, and a GUI. You do not have to configure all the components on each machine; rather, use the Installer to set up only the components that you want to run on a particular machine.

   Note: Keep in mind that you must configure the server on one machine, called the "server host". The server host normally also has the agent and GUI configured on it.

The Installer will ask you several questions to help you configure Aperi Storage Manager for your environment.


  1. Make sure you have a Java Runtime Environment (JRE) from IBM or Sun 1.5 installed on your machine. To check for Java on a machine, start a command prompt window (Start > Programs > Accessories > Command Prompt) and type java -version from a command line.
     If you see text similar to the following then continue to step 2:
     java version "1.5.0_07"
     Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_07-b03)
     Java HotSpot(TM) Client VM (build 1.5.0_07-b03, mixed mode)
     If you see text like the following, download the JRE from the IBM or Sun (http://java.sun.com/j2se/1.5.0/download.jsp) web sites before continuing:
     'java' is not recognized as an internal or external command, operable program or batch file.
  2. Set java into your PATH by typing the following at the command prompt:
     set path=%path%;C:\path_to_java_directory\jdk1.5.0_07\bin
     where path_to_java_directory represents the directory where the JRE is installed.
     Setting the Java path has two purposes: 1) it is used to run the Installer, and 2 ) it is stored in the Aperi startup scripts and used to run Aperi Storage Manager. This means that if you later uninstall the Java with this path, you won't be able to start Aperi Storage Manager until you reconfigure Aperi.
     Note: You can also edit the install.bat file or the System Path to contain the JRE pathname.
  3. Change to the [aperi_install_directory>\install subdirectory where you installed the Aperi Storage Manager files. For example, type cd c:\aperi\install ] and press Enter.
  4. Start the Installer using the following steps:
     Note: when running under Linux, you must first execute the following command against the cfgaperi file: chmod +x install
         * Type install and press Enter. Continue to the next section.
  5. Use the Installer

When the Installer starts, a graphical interface will appear:

  1. The welcome screen introduces the installer.  Press Next.  
  2. Read the license agreement.  Press Accept.
  3. Indicate which components you want to configure on the machine. If this is your first time, or you wish to do things "normally", accept the defaults and answer Next.
  4. Agent - If you are configuring the agent, you are asked to supply port value for the subagent. The subagent will open a socket on this port for communication with the server. You may choose any valid port number (0..65535) although, of course, you should not choose a port that are already in use. The only reason to override the default for this two question is when you know the default value is already in use.
  5. Server - Configure the servers: data, device, and report servers.  If you answered Yes to the server question in step 1, the following will appear:
     * Server hostname: [localhost]
     * Data server port: [9549]
     * Device server port: [9000]
     * Administrator group: [Administrators]
     * Report server repository path: [default path]


  6. Database - Either Derby or DB2.  If the database already exists, a new one will not be created.
     * Hostname: [localhost]
     * Port: [default]
     * Driver: [default]
     * Username (if db2)
     * Password (if db2)
  7. Installation Progress - Click install to begin the actual installation (configuration)


5. Uninstall Aperi Storage Manager

To uninstall Aperi:

  1. Shut down any Aperi components that are running. See Shut Down Aperi Storage Manager for instructions on how to shut down Aperi components.
  2. Delete the Aperi installation directory.