7 a.arora 1.5 ******************************************
8 * $Log: README,v $
9 * Revision 1.5 2004/03/05 18:00:00 amit
10 * Update and add some more information
11 *
12 * Revision 1.4 2001/02/26 10:39:08 karl
13 * Correct text
14 *
15 * Revision 1.3 2001/02/19 21:43:30 karl
16 * namespace creation
17 *
18 * $Author: karl $
19 ******************************************
20
21
22 TABLE OF CONTENTS
23 ===================
24
25 1. Introduction
26 2. How to setup Pegasus
27 3. How to setup Apache webserver
28 a.arora 1.5 4. How to setup the Pegasus webdemo
29 5. How to start the Pegasus webdemo
30
31
32 1. Introduction
33 == ============
34 This readme talks about the steps to setup Pegasus, Apache webserver and the
35 Pegasus webdemo on Windows and Linux platforms.
36 The pegasus/cgi directory contains the HTML CGI interface to Pegasus. It is
37 used as part of a demonstration of the Pegasus environment through a WEB
38 browser.
39
40 It consists of two** subdirectories:
41 1. htdocs : This directory contains the HTML forms that form the basis of the
42 demonstration. The starting point for the demo is index.html
43
44 2. cgi-bin: This directory contains the CGI executables. This consists of the
45 Pegasus CGIClient.exe program and the supporting shared libraries.
46 We have placed them in this directory despite the fact that they
47 also exist in the PEGASUS_HOME/bin directory to limit exposure to
48 other executables through CGI and to avoid a permanent path the
49 a.arora 1.5 $PEGASUS_HOME$/bin directory when Apache is executing.
50 **There is a third directory "icons" which has the logo for "Open Groups".
51
52 This demonstration uses the HTML pages in htdocs as forms to generate CGI
53 requests through the WEB Server. These requests are serviced by the Pegasus
54 CGIClient executable (copied to "cgi-bin" directory by the Makefile in this
55 directory). CGIClient, in turn converts the CGI forms input to Pegasus CIM
56 Operations C++ calls. The Pegasus client library converts the calls to XML
57 conforming with the DMTF CIM Operations over HTTP specifications and passes
58 them to the Pegasus CIM Server.
59
60 The CIM server responses in XML are interpreted by the CGI client (part of the
61 SDK code) which then generates appropriate HTML responses and passes them back
62 to the WEB server.
63
64 NOTE: By default, the CGIClient fixes the address and port of the CIM server as
65 ---- URL : localhost
66 Port : 5988
67 This can be changed by using "Define Host" option provided in the demo.
68
69 If you have already got Pegasus installed and configured, please jump to
70 a.arora 1.5 "3. How to setup Apache webserver".
71
72
73
74 2. How to setup Pegasus
75 == ===================
76 A. On Windows platform
77 -- -------------------
78 Environment setup:
79 ==================
80 1. MS Visual Studio VC++ (tested on .NET 2003 (Version 7.1))
81 2. A CVS client (say WinCVS 1.2 @ http://www.wincvs.org/download.html)
82 3. GNU-make 3.79 for Windows (@ http://ftp.gnu.org/pub/gnu/make/)
83 It should be compiled using NMake (NMake comes with VC++). For details
84 on how to work with NMake, please refer to Readme file(s) which comes
85 with the GNU-make source code.
86 NOTE: The latest GNU-make for Windows can also be found at
87 ---- "http://www.openpegasus.org/pb/index.tpl".
88
89
90 Downloading Pegasus source tree:
91 a.arora 1.5 ================================
92 There are two options for downloading Pegasus source code:
93 1. Source from CVS:
94 Download Pegasus sourcetree from www.pegasus.org (say in <Drive>:\<pegtop>).
95 If using WinCVS to download, please use following settings:
96 a> Go to "Admin" menu option and select "Preferences"
97 b> In "General" tab, set CVSROOT to ":pserver:anon@cvs.opengroup.org:
98 /cvs/MSB"
99 c> Set Authentication to '"passwd" file on CVS server' (this option is
100 there in "General" tab under Admin->Preferences).
101 d> In "WinCVS" tab (again, under Admin->Preferences) set Home to
102 "<Drive>:\<pegtop>"
103 e> Go to "Admin" menu option and select "login"
104 f> Give "anon" as the password when prompted
105 g> Type "cvs checkout pegasus" in the command line menu option under
106 "Admin".
107 2. Source from www.openpegasus.org
108 There is a snapshot of the latest release of Pegasus (eg. Pegasus
109 2.3.1) on the pegasus home page http://www.openpegasus.org. The release
110 is present under the Recent Documents (eg. "Release 2.3.1 - zip format
111 (Windows)"). You may download the source from this link.
112 a.arora 1.5
113
114
115 Building Pegasus:
116 =================
117 1. Export following environment variables with suitable values.
118 For an example:
119 set PEGASUS_ROOT=<Drive>:/<pegtop>/pegasus
120 set PEGASUS_HOME=<Drive>:/<pegtop>/pegasus
121 set PEGASUS_PLATFORM=WIN32_IX86_MSVC
122 NOTE: a> You might have to use "\" in the path instead of "/".
123 ---- b> These variables can be exported from the command window
124 manually each time you need to compile/run Pegasus, or you can
125 add them as "System Variables" in "My Computer" -(right
126 click)->"Properties"-->"Advanced"--> "Environment variables".
127 2. Make sure that you execute "vsvars32.bat" ("vcvars32.bat" in Visual
128 Studio 6.0) file (comes with Visual Studio) every time you open a new
129 command prompt Window before issuing any compilation (NMake or make).
130 Or else, you may also set PATH environment variable to point to Visual
131 Studio paths.
132 3. Compile MU.exe (Unix-commands emulator for Windows) by issuing a make
133 a.arora 1.5 in the "<Drive>:\<pegtop>\pegasus\src\utils\mu" folder. Make sure that
134 MU.exe exists in "<Drive>:\<pegtop>\pegasus\bin" folder. If not, copy
135 it here.
136 4. Add "<Drive>:\<pegtop>\pegasus\bin" directory to the PATH environment
137 variable.
138
139 5. Issue following commands in pegasus home directory
140 (<Drive>:\<pegtop>\pegasus)
141 a> make : (This comand may take 10 to 30 minutes depending on your
142 machine's configuration. If you don't see any error message
143 on the screen, the compilation would have gone fine. You
144 may still confirm this by checking for "cimserver.exe" file
145 in "<Drive>:\<pegtop>\bin" path. In case of any error, check
146 the error message on the screen and try to correct it. Some
147 of the common problems faced are:
148 i > "cl.exe : File Not Found." (This implies that you haven't
149 executed step# 2).
150 ii> "<Drive>:<pegtop><some-path> Not Found" (Try changing the
151 slash in the path exported by PEGASUS_HOME. If using
152 "/", replace it with "\" and vice-versa.
153 iii> For some other error, try to solve it, or else you may ask
154 a.arora 1.5 your query on "pegasus-l@opengroup.org" mailing list
155 giving a detailed description of the problem (preferably
156 with some snapshots).
157
158 b> make repository : (This command may take 5 to 10 minutes, again
159 depending on your machine's configuration.
160 c> make tests (optional) : (This command may take roughly 5 minutes).
161
162 Starting the CIM Server:
163 ========================
164 1. From Command prompt, type cimserver. This would start it (inorder to
165 stop issue "cimserver -s" command). You can issue "cimprovider -l"
166 command to verify that the cimserver is running fine. This command
167 would tell you if the server is not running.
168 2. There are various command line clients present in pegasus which
169 provide/configure some of the basic features of the cimserver. Some of
170 these are:
171 cimconfig - To list/change/setup configuration parameters for
172 cimserver.
173 cimprovider- To list/load/unload/delete/ various providers.
174 cimmof - This command operates through the client interface and
175 a.arora 1.5 acts as a remote compiler for MOF files against an active
176 CIM Repository.
177 cimmofl - This command is also used to compile the MOF files, but it
178 operates locally and directly against the repository.
179 cimauth - For configuring/ listing authorization support.
180 cimuser - For listing/adding/deleting/modifying users to access the
181 pegasus repository.
182 3. There is a command line utility CLI for running individual cim
183 operations.
184 "CLI -h" to get help for the usage of this client.
185
186
187
188 B. On Linux Platform
189 -- -----------------
190 Environment setup:
191 ==================
192 RedHat Linux 8.0 on IA32 with gcc-3.x
193
194 Downloading Pegasus source tree:
195 ================================
196 a.arora 1.5 There are 2 options for downloading pegasus sources on your local machine:
197 1. Source from CVS.
198 Commands for fetching the Pegasus source code using CVS are:
199 a> Export the CVSROOT environment variable:
200 "export CVSROOT=:pserver:anon@cvs.opengroup.org:/cvs/MSB"
201 b> Run "cvs login" command. When it prompts for the password give
202 "anon".
203 c> Execute "cvs checkout pegasus".
204 NOTE: Refer the note in "How To Setup the Pegasus WebDemo (on Linux)"
205 ---- for selecting the path where Pegasus code should be put.
206 Once the source tree has been checked out it can be updated regularly
207 (as required) by running "cvs update -d".
208 2. Source from www.openpegasus.org
209 There is a snapshot of the latest release of Pegasus (eg. Pegasus
210 2.3.1) on the pegasus home page http://www.openpegasus.org. The release
211 is present under the Recent Documents (eg. "Release 2.3.1 - compressed
212 tar format (Linux)"). You may download the source from this link.
213
214
215 Setting up Pegasus
216 ==================
217 a.arora 1.5 1. Open .bash_profile in your home directory ~<username>/.bash_profile
218
219 2. Write the following statements into .bash_profile in order to setup
220 Pegasus variables (replace <pegtop> with the path where you want to put
221 Pegasus source tree):
222 PEGASUS_HOME=/<pegtop>/pegasus/
223 PEGASUS_ROOT=/<pegtop>/pegasus/
224 PEGASUS_PLATFORM=LINUX_IX86_GNU
225 export PEGASUS_HOME PEGASUS_ROOT PEGASUS_PLATFORM
226 export PATH=$PATH:/<pegtop>/pegasus/bin
227
228 NOTE: You may keep the PEGASUS_HOME and PEGASUS_ROOT as different
229 ---- paths. This would allow you to install the binaries, libraries
230 and the repository in a different path and not in the same path
231 as the Pegasus source code. If they are different, please make
232 sure that the paths exist.
233 3. Logout and Re-login to your account and change directory to
234 pegasus/(the one we created in the step above).
235 [The logout and login is to make sure that your .bash_profile is
236 executed so that the PEGASUS_XXXX variables are set to their respective
237 values. You may also execute .bash_profile manually
238 a.arora 1.5 (". ~/.bash_profile") thus avoiding the logout/login process.]
239 4. Check your system if gcc-3.x is installed. Run "g++ --version" to check
240 the version. If you are using Redhat linux then it would show something
241 like this: "g++ (GCC) 3.2 20020903 (Red Hat Linux 8.0 3.2-7) Copyright
242 (C) 2002 Free Software Foundation, Inc. This is free software; see the
243 source for copying conditions. There is NO warranty; not even for
244 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE."
245
246 Building Pegasus
247 ================
248 1. Change directory to the one in which pegasus sources are present and
249 execute "make" OR "make 2>&1 | tee make.log"
250 [The command "make 2>&1 | tee make.log" is just to keep a build log for
251 your reference, and is not mandatory. This log may be helpful in
252 detecting problems that might arise during build.
253 2. Run "make repository" OR "make repository 2>&1 | tee make-
254 repository.log". This will create a directory repository/ under the
255 PEGASUS_ROOT directory, which contains the classes and instances for
256 all namespaces present in the project. All the MOFs are compiled during
257 this "make repository", and the XMLs generated are put in the
258 "repository" directory.
259 a.arora 1.5 3. To execute all the basic tests present in Pegasus sources, execute
260 "make tests" and execute "make -f TestMakefile tests" to run all the
261 tests specified in the TestMakefile.
262
263
264 Starting the CIM Server:
265 ========================
266 1. To start the pegasus server just run: "cimserver"
267 You may use "cimprovider -l" command to verify if the cimserver is
268 running or not.
269 To stop: "cimserver -s".
270 [Remember: To stop the cimserver you need to have root access. If you
271 started the cimserver from a non-user account you will have to
272 explicitly kill it by issuing "killall cimserver"]
273 2. There are various clients present in pegasus which provide/configure
274 some of the basic features of the cimserver. Some of these commands
275 are:
276 cimconfig - To list/change/setup configuration parameters for
277 cimserver.
278 cimprovider- To list/load/unload/delete/ various providers.
279 cimmof - This command operates through the client interface and
280 a.arora 1.5 acts as a remote compiler for MOF files against an active
281 CIM Repository.
282 cimmofl - This command is also used to compile the MOF files, but it
283 operates.
284 locally and directly against the repository.
285 cimauth - For configuring/ listing authorization support.
286 cimuser - For listing/adding/deleting/modifying users to access the
287 pegasus repository.
288 3. There is a command line utility CLI for running individual cim
289 operations. Execute "CLI ?" to get a list of operations supported by
290 pegasus currently.
291 "CLI -h" to get help for the usage of this client.
292
293
294 3. How to setup Apache webserver
295 == =============================
296 A. On Windows platform
297 -- -------------------
298 Download and install Apache webserver (Httpd) (binary version) for Windows
299 from www.apache.org (http://httpd.apache.org/download.cgi).
300
301 a.arora 1.5 B. On Linux platform
302 -- -----------------
303 Download the Apache webserver (Httpd) code for Linux from www.apache.org
304 (http://httpd.apache.org/download.cgi).
305 Follow the instructions in the README file to build and install Httpd.
306
307
308
309 4. How to setup the Pegasus webdemo
310 == ================================
311 A. On Windows platform
312 -- -------------------
313 Modify the httpd.conf (this file can be found in "<apache-install-dir>\conf"
314 folder) Apache configuration file with the following Entries (do not forget
315 to replace <pegtop> with the path where you have put the Pegasus source code):
316 #PEGASUS
317 ScriptAlias /pegasus/cgi-bin/CGIClient "<Drive>:/<pegtop>/pegasus/cgi/cgi-bin/CGIClient.exe"
318 ScriptAlias /pegasus/cgi-bin "<Drive>:/<pegtop>/pegasus/cgi/cgi-bin"
319 Alias /pegasus/icons "<Drive>:/<pegtop>/pegasus/cgi/icons"
320 Alias /pegasus "<Drive>:/<pegtop>/pegasus/cgi/htdocs"
321
322 a.arora 1.5 <Directory "<Drive>:/<pegtop>/pegasus/cgi/cgi-bin">
323 AllowOverride None
324 Options ExecCGI
325 allow from all
326 </Directory>
327
328
329 B. On Linux platform
330 -- -----------------
331 Modify the httpd.conf (it can be found in "<Apache-install-path>/conf"
332 directory. The default value of <Apache-install-path> is "/usr/local/apache")
333 Apache configuration file with the following Entries (do not forget to replace
334 <pegtop> with the path where you have put the Pegasus source code) :
335 #PEGASUS
336 ScriptAlias /pegasus/cgi-bin/CGIClient "/<pegtop>/pegasus/cgi/cgi-bin/CGIClient"
337 ScriptAlias /pegasus/cgi-bin "/<pegtop>/pegasus/cgi/cgi-bin"
338 Alias /pegasus/icons "/<pegtop>/pegasus/cgi/icons"
339 Alias /pegasus "/<pegtop>/pegasus/cgi/htdocs"
340
341 <Directory "/<pegtop>/pegasus/cgi/cgi-bin">
342 AllowOverride None
343 a.arora 1.5 Options ExecCGI
344 allow from all
345 </Directory>
346
347 NOTE: Please make sure that each directory in the path "/<pegtop>/pegasus
348 ---- /cgi/cgi-bin/" has execute permission for "nobody" user (Apache
349 httpd uses this userid to access files on the server, when a client
350 request comes in). This can be done by giving "x" permission in
351 "others" for all the directories.
352 Giving execute permission to all the directories may be a security
353 concern for some users when they have the Pegasus source tree in
354 their home directories. In this case, there are two options:
355 1> Put the Pegasus source tree in some other path (eg. "/pegasus"),
356 and not in home directory.
357 2> Copy the entire cgi directory tree from "/<pegtop>/pegasus/cgi"
358 to put it in some path where you can give execute permission to
359 "others".
360
361
362 5. How to start the Pegasus webdemo
363 == ================================
364 a.arora 1.5 A> Give a "make" in <pegtop>/pegasus/cgi to get the necessary executables
365 copied (CGIClient program, etc) to cgi-bin.
366 B> Open a web-browser from a client machine and put the following URL in it:
367 "http://<host-addr>/pegasus"
368 where <host-addr> can be the "localhost" (if the client machine is same
369 as the server), or a valid IP address of the server (machine hosting
370 the Pegasus webdemo and the Apache server).
371 C> You would see the index.html (under pegasus/cgi/htdocs path) loaded in the
372 browser. Follow the instructions mentioned and have fun !
373
|