//%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 :\). 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 ":\" 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=://pegasus set PEGASUS_HOME=://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 ":\\pegasus\src\utils\mu" folder. Make sure that MU.exe exists in ":\\pegasus\bin" folder. If not, copy it here. 4. Add ":\\pegasus\bin" directory to the PATH environment variable. 5. Issue following commands in pegasus home directory (:\\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 ":\\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> ": 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 ~/.bash_profile 2. Write the following statements into .bash_profile in order to setup Pegasus variables (replace with the path where you want to put Pegasus source tree): PEGASUS_HOME=//pegasus/ PEGASUS_ROOT=//pegasus/ PEGASUS_PLATFORM=LINUX_IX86_GNU export PEGASUS_HOME PEGASUS_ROOT PEGASUS_PLATFORM export PATH=$PATH://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 "\conf" folder) Apache configuration file with the following Entries (do not forget to replace with the path where you have put the Pegasus source code): #PEGASUS ScriptAlias /pegasus/cgi-bin/CGIClient "://pegasus/cgi/cgi-bin/CGIClient.exe" ScriptAlias /pegasus/cgi-bin "://pegasus/cgi/cgi-bin" Alias /pegasus/icons "://pegasus/cgi/icons" Alias /pegasus "://pegasus/cgi/htdocs" ://pegasus/cgi/cgi-bin"> AllowOverride None Options ExecCGI allow from all B. On Linux platform -- ----------------- Modify the httpd.conf (it can be found in "/conf" directory. The default value of is "/usr/local/apache") Apache configuration file with the following Entries (do not forget to replace with the path where you have put the Pegasus source code) : #PEGASUS ScriptAlias /pegasus/cgi-bin/CGIClient "//pegasus/cgi/cgi-bin/CGIClient" ScriptAlias /pegasus/cgi-bin "//pegasus/cgi/cgi-bin" Alias /pegasus/icons "//pegasus/cgi/icons" Alias /pegasus "//pegasus/cgi/htdocs" /pegasus/cgi/cgi-bin"> AllowOverride None Options ExecCGI allow from all NOTE: Please make sure that each directory in the path "//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 "//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 /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:///pegasus" where 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 !