Return to README CVS log

Up to [Pegasus] / pegasus / cgi

BUG#: 7860
TITLE: pegasus/cgi directory is obsolete
DESCRIPTION: Remove unused files.

//%2006////////////////////////////////////////////////////////////////////////
//
// Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development
// Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.
// Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;
// IBM Corp.; EMC Corporation, The Open Group.
// Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
// IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.
// Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
// EMC Corporation; VERITAS Software Corporation; The Open Group.
// Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
// EMC Corporation; Symantec Corporation; The Open Group.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to
// deal in the Software without restriction, including without limitation the
// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
// sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
// 
// THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
// ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
// "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
// LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
// PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
// ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
// WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
//
//==============================================================================


The Pegasus WEB Demonstration
=============================


TABLE  OF  CONTENTS
===================

1. Introduction
2. How to setup Pegasus
3. How to setup Apache webserver
4. How to setup the Pegasus webdemo 
5. How to start the Pegasus webdemo


1. Introduction
== ============
 This readme talks about the steps to setup Pegasus, Apache webserver and the
 Pegasus webdemo on Windows and Linux platforms.
 The pegasus/cgi directory contains the HTML CGI interface to Pegasus. It is 
 used as part of a demonstration of the Pegasus environment through a WEB 
 browser.

 It consists of two** subdirectories:
 1. htdocs : This directory contains the HTML forms that form the basis of the
             demonstration. The starting point for the demo is index.html
 
 2. cgi-bin: This directory contains the CGI executables.  This consists of the
             Pegasus CGIClient.exe program and the supporting shared libraries.  
             We have placed them in this directory despite the fact that they 
             also exist in the PEGASUS_HOME/bin directory to limit exposure to 
             other executables through CGI and to avoid a permanent path the                   
             $PEGASUS_HOME$/bin directory when Apache is executing.
  **There is a third directory "icons" which has the logo for "Open Groups".

 This demonstration uses the HTML pages in htdocs as forms to generate CGI
 requests through the WEB Server.  These requests are serviced by the Pegasus
 CGIClient executable (copied to "cgi-bin" directory by the Makefile in this 
 directory). CGIClient, in turn converts the CGI forms input to Pegasus CIM  
 Operations C++ calls. The Pegasus client library converts the calls to XML 
 conforming with the DMTF CIM Operations over HTTP specifications and passes 
 them to the Pegasus CIM Server.

 The CIM server responses in XML are interpreted by the CGI client (part of the  
 SDK code) which then generates appropriate HTML responses and passes them back 
 to the WEB server.

 NOTE: By default, the CGIClient fixes the address and port of the CIM server as
 ----   URL  : localhost
        Port : 5988
       This can be changed by using "Define Host" option provided in the demo.

 If you have already got Pegasus installed and configured, please jump to
 "3. How to setup Apache webserver". 



2. How to setup Pegasus
== ===================
   A. On Windows platform
   -- -------------------
      Environment setup:
      ==================
      1. MS Visual Studio VC++ (tested on .NET  2003 (Version 7.1))
      2. A CVS client (say WinCVS 1.2 @ http://www.wincvs.org/download.html) 
      3. GNU-make 3.79 for Windows (@ http://ftp.gnu.org/pub/gnu/make/)
         It should be compiled using NMake (NMake comes with VC++). For details
         on how to work with NMake, please refer to Readme file(s) which comes
         with the GNU-make source code.
         NOTE: The latest GNU-make for Windows can also be found at 
         ----  "http://www.openpegasus.org/pb/index.tpl".
          
        
      Downloading Pegasus source tree:
      ================================
      There are two options for downloading Pegasus source code:
      1. Source from CVS:
         Download Pegasus sourcetree from www.pegasus.org (say in <Drive>:\<pegtop>).
         If using WinCVS to download, please use following settings:
          a>  Go to "Admin" menu option and select "Preferences"
          b>  In "General" tab, set CVSROOT  to ":pserver:anon@cvs.opengroup.org:
              /cvs/MSB"
          c>  Set Authentication to '"passwd" file on CVS server' (this option is
              there in "General" tab under Admin->Preferences).
          d>  In "WinCVS" tab (again, under Admin->Preferences) set  Home to 
              "<Drive>:\<pegtop>"
          e>  Go to "Admin" menu option and select "login"
          f>  Give "anon" as the password when prompted
          g>  Type "cvs checkout pegasus"  in the command line menu option under 
              "Admin".
      2. Source from www.openpegasus.org
         There is a snapshot of the latest release of Pegasus (eg. Pegasus 
         2.3.1) on the pegasus home page http://www.openpegasus.org. The release  
         is present under the Recent Documents (eg. "Release 2.3.1 - zip format 
         (Windows)"). You may download the source from this link.
      
      

      Building Pegasus:
      =================
      1. Export following environment variables with suitable values.
         For an example:
          set  PEGASUS_ROOT=<Drive>:/<pegtop>/pegasus
          set  PEGASUS_HOME=<Drive>:/<pegtop>/pegasus
          set  PEGASUS_PLATFORM=WIN32_IX86_MSVC
         NOTE: a> You might have to use "\" in the path instead of "/". 
         ----  b> These variables can be exported from the command window 
                  manually each time you need to compile/run Pegasus, or you can 
                  add them as "System Variables" in "My Computer" -(right 
                  click)->"Properties"-->"Advanced"--> "Environment variables".
      2. Make sure that you execute "vsvars32.bat" ("vcvars32.bat" in Visual
         Studio 6.0) file (comes with Visual Studio) every time you open a new
         command prompt Window before issuing any compilation (NMake or make).
         Or else, you may also set PATH environment variable to point to Visual
         Studio paths.
      3. Compile MU.exe  (Unix-commands emulator for Windows) by issuing a make 
         in the "<Drive>:\<pegtop>\pegasus\src\utils\mu" folder. Make sure that
         MU.exe exists in "<Drive>:\<pegtop>\pegasus\bin" folder. If not, copy
         it here.
      4. Add "<Drive>:\<pegtop>\pegasus\bin"  directory to the PATH environment 
         variable.
      
      5. Issue following commands in pegasus home directory 
         (<Drive>:\<pegtop>\pegasus)
          a>  make : (This comand may take 10 to 30 minutes depending on your 
                      machine's configuration. If you don't see any error message
                      on the screen, the compilation would have gone fine. You
                      may still confirm this by checking for "cimserver.exe" file
                      in "<Drive>:\<pegtop>\bin" path. In case of any error, check
                      the error message on the screen and try to correct it. Some
                      of the common problems faced are: 
                      i > "cl.exe : File Not Found." (This implies that you haven't
                                 executed step# 2).
                      ii> "<Drive>:<pegtop><some-path>  Not Found" (Try changing the
                                 slash in the path exported by PEGASUS_HOME. If using
                                 "/", replace it with "\" and vice-versa.
                      iii> For some other error, try to solve it, or else you may ask
                           your query on "pegasus-l@opengroup.org" mailing list
                           giving a detailed description of the problem (preferably 
                           with some snapshots).
                   
          b>  make repository : (This command may take 5 to 10 minutes, again
                      depending on your machine's configuration.
          c>  make tests (optional) : (This command may take roughly 5 minutes).

      Starting the CIM Server:
      ========================
      1. From Command prompt, type cimserver. This would start it (inorder to 
         stop issue "cimserver -s" command). You can issue "cimprovider -l" 
         command to verify that the cimserver is running fine. This command 
         would tell you if the server is not running.
      2. There are various command line clients present in pegasus which 
         provide/configure some of the basic features of the cimserver. Some of 
         these are:
         cimconfig  - To list/change/setup configuration parameters for 
                      cimserver.
         cimprovider- To list/load/unload/delete/ various providers.
         cimmof     - This command operates through the client interface and  
                      acts as a remote compiler for MOF files against an active 
                      CIM Repository.                    
         cimmofl    - This command is also used to compile the MOF files, but it 
                      operates locally and directly against the repository.
         cimauth    - For configuring/ listing authorization support.
         cimuser    - For listing/adding/deleting/modifying users to access the 
                      pegasus repository.
      3. There is a command line utility CLI for running individual cim 
         operations.
         "CLI -h" to get help for the usage of this client.



   B. On Linux Platform
   -- -----------------      
      Environment setup:
      ==================
      RedHat Linux 8.0 on IA32 with gcc-3.x

      Downloading Pegasus source tree:
      ================================
      There are 2 options for downloading pegasus sources on your local machine:
      1. Source from CVS.
         Commands for fetching the Pegasus source code using CVS are:
          a> Export the CVSROOT environment variable:
             "export CVSROOT=:pserver:anon@cvs.opengroup.org:/cvs/MSB"
          b> Run "cvs login" command. When it prompts for the password give 
             "anon".
          c> Execute "cvs checkout pegasus".
         NOTE: Refer the note in "How To Setup the Pegasus WebDemo (on Linux)" 
         ----  for selecting the path where Pegasus code should be put.
         Once the source tree has been checked out it can be updated regularly
         (as required) by running "cvs update -d".
      2. Source from www.openpegasus.org
         There is a snapshot of the latest release of Pegasus (eg. Pegasus 
         2.3.1) on the pegasus home page http://www.openpegasus.org. The release 
         is present under the Recent Documents (eg. "Release 2.3.1 - compressed 
         tar format (Linux)"). You may download the source from this link.
                
      
      Setting up Pegasus
      ==================
      1. Open .bash_profile in your home directory  ~<username>/.bash_profile

      2. Write the following statements into .bash_profile in order to setup 
         Pegasus variables (replace <pegtop> with the path where you want to put 
         Pegasus source tree):
          PEGASUS_HOME=/<pegtop>/pegasus/
          PEGASUS_ROOT=/<pegtop>/pegasus/
          PEGASUS_PLATFORM=LINUX_IX86_GNU
          export PEGASUS_HOME PEGASUS_ROOT PEGASUS_PLATFORM
          export PATH=$PATH:/<pegtop>/pegasus/bin

         NOTE: You may keep the PEGASUS_HOME and PEGASUS_ROOT as different 
         ----  paths. This would allow you to install the binaries, libraries 
               and the repository in a different path and not in the same path 
               as the Pegasus source code. If they are different, please make 
               sure that the paths exist.
      3. Logout and Re-login to your account and change directory to 
         pegasus/(the one we created in the step above).
         [The logout and login is to make sure that your .bash_profile is 
         executed so that the PEGASUS_XXXX variables are set to their respective 
         values. You may also execute .bash_profile manually 
         (". ~/.bash_profile") thus avoiding the logout/login process.]
      4. Check your system if gcc-3.x is installed. Run "g++ --version" to check 
         the version. If you are using Redhat linux then it would show something 
         like this: "g++ (GCC) 3.2 20020903 (Red Hat Linux 8.0 3.2-7) Copyright 
         (C) 2002 Free Software Foundation, Inc. This is free software; see the 
         source for copying conditions. There is NO warranty; not even for 
         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE."

      Building Pegasus
      ================
      1. Change directory to the one in which pegasus sources are present and 
         execute "make" OR "make 2>&1 | tee make.log" 
         [The command "make 2>&1 | tee make.log" is just to keep a build log for 
         your reference, and is not mandatory. This log may be helpful in 
         detecting problems that might arise during build.
      2. Run "make repository" OR "make repository 2>&1 | tee make-
         repository.log". This will create a directory repository/ under the 
         PEGASUS_ROOT directory, which contains the classes and instances for 
         all namespaces present in the project. All the MOFs are compiled during 
         this "make repository", and the XMLs generated are put in the  
         "repository" directory.
      3. To execute all the basic tests present in Pegasus sources, execute  
         "make tests" and execute "make -f TestMakefile tests" to run all the 
         tests specified in the TestMakefile.


      Starting the CIM Server:
      ========================
      1. To start the pegasus server just run: "cimserver" 
         You may use "cimprovider -l" command to verify if the cimserver is
         running or not.
         To stop: "cimserver -s".
         [Remember: To stop the cimserver you need to have root access. If you
         started the cimserver from a non-user account you will have to 
         explicitly kill it by issuing "killall cimserver"]
      2. There are various clients present in pegasus which provide/configure 
         some of the basic features of the cimserver. Some of these commands 
         are:
         cimconfig  - To list/change/setup configuration parameters for 
                      cimserver.
         cimprovider- To list/load/unload/delete/ various providers.
         cimmof     - This command operates through the client interface and 
                      acts as a remote compiler for MOF files against an active 
                      CIM Repository.                    
         cimmofl    - This command is also used to compile the MOF files, but it 
                      operates.
                      locally and directly against the repository.
         cimauth    - For configuring/ listing authorization support.
         cimuser    - For listing/adding/deleting/modifying users to access the 
                      pegasus repository.
      3. There is a command line utility CLI for running individual cim 
         operations.  Execute "CLI ?" to get a list of operations supported by 
         pegasus currently.
         "CLI -h" to get help for the usage of this client.


3. How to setup Apache webserver
== =============================
   A. On Windows platform
   -- -------------------
      Download and install Apache webserver (Httpd) (binary version) for Windows 
      from www.apache.org (http://httpd.apache.org/download.cgi).
 
   B. On Linux platform
   -- -----------------
      Download the Apache webserver (Httpd) code for Linux from www.apache.org
      (http://httpd.apache.org/download.cgi).
      Follow the instructions in the README file to build and install Httpd.
 


4. How to setup the Pegasus webdemo 
== ================================
   A. On Windows platform
   -- -------------------
      Modify the httpd.conf (this file can be found in "<apache-install-dir>\conf"
      folder) Apache configuration file with the following Entries (do not forget
      to replace <pegtop> with the path where you have put the Pegasus source code):
#PEGASUS
ScriptAlias /pegasus/cgi-bin/CGIClient "<Drive>:/<pegtop>/pegasus/cgi/cgi-bin/CGIClient.exe"
ScriptAlias /pegasus/cgi-bin "<Drive>:/<pegtop>/pegasus/cgi/cgi-bin"
Alias /pegasus/icons "<Drive>:/<pegtop>/pegasus/cgi/icons"
Alias /pegasus "<Drive>:/<pegtop>/pegasus/cgi/htdocs"

<Directory "<Drive>:/<pegtop>/pegasus/cgi/cgi-bin">
AllowOverride None
Options ExecCGI
allow from all
</Directory>


   B. On Linux platform
   -- -----------------
      Modify the httpd.conf (it can be found in "<Apache-install-path>/conf"
      directory. The default value of <Apache-install-path> is "/usr/local/apache")
      Apache configuration file with the following Entries (do not forget to replace
      <pegtop> with the path where you have put the Pegasus source code) :
#PEGASUS
ScriptAlias /pegasus/cgi-bin/CGIClient "/<pegtop>/pegasus/cgi/cgi-bin/CGIClient"
ScriptAlias /pegasus/cgi-bin "/<pegtop>/pegasus/cgi/cgi-bin"
Alias /pegasus/icons "/<pegtop>/pegasus/cgi/icons"
Alias /pegasus "/<pegtop>/pegasus/cgi/htdocs"

<Directory "/<pegtop>/pegasus/cgi/cgi-bin">
AllowOverride None
Options ExecCGI
allow from all
</Directory>      
      
      NOTE: Please make sure that each directory in the path "/<pegtop>/pegasus
      ----  /cgi/cgi-bin/" has execute permission for "nobody" user (Apache 
            httpd uses this userid to access files on the server, when a client 
            request comes in). This can be done by giving "x" permission in 
            "others" for all the directories. 
            Giving execute permission to all the directories may be a security
            concern for some users when they have the Pegasus source tree in 
            their home directories. In this case, there are two options:
             1> Put the Pegasus source tree in some other path (eg. "/pegasus"), 
                and not in home directory.
             2> Copy the entire cgi directory tree from "/<pegtop>/pegasus/cgi" 
                to put it in some path where you can give execute permission to 
                "others".


5. How to start the Pegasus webdemo
== ================================
     A> Give a "make" in <pegtop>/pegasus/cgi to get the necessary executables
        copied (CGIClient program, etc) to cgi-bin.
     B> Open a web-browser from a client machine and put the following URL in it:
        "http://<host-addr>/pegasus"
        where <host-addr> can be the "localhost" (if the client machine is same
        as the server), or a valid IP address of the server (machine hosting 
        the Pegasus webdemo and the Apache server).
     C> You would see the index.html (under pegasus/cgi/htdocs path) loaded in the
        browser. Follow the instructions mentioned and have fun !